Lesson 03: How to create and run a Python project

This lesson is dedicated to how to create and execute Python programming projects. The lesson begins by defining and drawing the usual structure of a project and also mentions the structure of projects that can be published in PyPI. In the first part, an attempt is made to create a complete picture of the structure of a project in the reader’s mind, and through this, he becomes familiar with the definitions of “package”, “module” and “script” in the Python language. The next two sections focus on how to create a script and how to execute it, while pointing to two ways to execute Python commands; Because Python projects are run this way. In the following, the process of code execution by Python interpreter as well as the introduction of bytecode and finally the introduction of virtualenv and pyvenv are discussed.

✔ Level: Basic

Project structure

The first step in developing a Python program is to create a project, after which you start writing code or creating the source code of the program.

The source code of a Python project is developed in the form of one or more “modules”. In source code with more than one module, it is better to put the modules that are logically related to each other in separate directories that Directories in the Python language are called “packages”.

tip

One or more modules within a specific directory form a packet, and each packet can contain another packet (s).

Attention

From version 3.3 of Python, with the addition of a new feature called the Namespace Package ( PEP 420 ), the definition of the Python package is expanded into two categories: the Regular Package, which is the same old definition of the package, and the Spatial Package. . [Will be explained more in the module lesson]

There are two types of modules in the Python language definition:

1. Pure Module is the normal definition of Python module; Files with the extension py in which Python code (definitions and commands) are written.

2. Extension Module, modules created by programming languages other than Python. Remember lesson 1 that Python is an extensible language, and that code written in other programming languages can be used alongside it, such as C and C ++ in implementing CPython, or Java in implementing Jython, or # C in implementing IronPython. [The creation and use of this type of module will be examined in a separate lesson.]

Attention

From now on, anywhere in the book that says “Module” means Pure Module, unless the name “Development Module” is explicitly mentioned.

There is no requirement to follow a specific structure when creating a Python project, and even the source code of a project can contain only one module. For example, consider the following diagram of a hypothetical SampleProject project:

SampleProject
.
├── sample_project.py
├── module_one.py
└── pakage/
    ├── __init__.py
    ├── module_two.py
    └── module_three.py

tip

In Python, every (normal) package must contain a special init __. Py__ file, which of course does not need to be coded within this file. This file introduces itself to the Python interpreter as a package (a place to find modules).

In creating the source code, the whole program must be executed by running a specific module. This module is also commonly referred to as a project and is referred to as a “script” (here: ‌ sample_project.py). In fact, a script is a module that is developed for the purpose of executing a program, and the creation of source code also begins from it. However, as we know, one of the features of the Python programming possible modular ( Modular ) is in this way that we can own codes, as needed in the modules individually, wrote the import (Import) of the script (or other modules) of code within They used them. By this logic, the source code of a Python project can be thought of as containing only one script that can be extended by a number of modules; Of course, the modules may also be placed in separate packages as needed.

tip

[ PEP 8 ]: Only lowercase letters are used in naming modules, and the underscore ( _) character can also be used if needed . Package names are short and consist of lowercase letters; Use _in package name is not recommended.

You now have enough information to start a Python project, but if you want to get acquainted with the proper structure of a project that is going to be published for other people through PyPI or services like github.com (like an application library), read on. Read. Otherwise you can skip to the next section of this lesson .

Apart from the source code, it is necessary to consider other items in the structure of this type of projects; Note the structure below:

SampleProject
.
├── docs/
├── LICENSE.txt
├── MANIFEST.in
├── README.rst
├── requirements.txt
├── sampleproject/
│   ├── __init__.py
│   ├── module_one.py
│   ├── pakage/
│   │   ├── __init__.py
│   │   ├── module_two.py
│   │   └── module_three.py
│   ├── sample_project.py
│   └── test/
├── setup.cfg
└── setup.py

The initial structure consisted only of source code, but in this structure all the source code in the form of a Python package is part of a larger set in which a series of files such as requirements.txt, README.rst and setup.py with two directories docs and test Added. The following explains a bit about the use of these cases, but it is emphasized that there is no need to follow this structure at the moment, and at the end of the book, you will get acquainted with them by creating a practical project and placing it on github.com and PyPI. [You can use Python documents for more information ]

setup.py : This important file has two functions: 1- Project configuration which is done through ready-made function arguments ()setupinside this file. 2- A command line interface to execute application commands related to the project (similar pattern:) .<python setup.py <commands

The list of these commands can be viewed by entering the same command .python setup.py –help-commands

setup.cfg : has a structure similar to an ini file , and if necessary, the options related to the setup.py command line commands are defined in this file. You can follow the pattern to see a list of options for a specific command .<python setup.py –help <commands

README.rst : All projects must include a document to describe themselves. Python usually uses the reStructuredText markup language to create documents , so these documents have the rst extension, which is not mandatory, and you can also use the Markdown (md extension) to create this file .

MANIFEST.in : This file is usually used to introduce non-Python files in the project. When you want to create a “distribution source” or sdist of a project (similar command:) only certain files of the project are identified and the rest of the files (if any) must be identified by this file (albeit with a specific pattern ).python setup.py sdist

requirements.txt : This file is used to introduce specific libraries that have been used in the project and that must be present or installed when the source code is installed or executed.

LICENSE.txt : This file contains the project publishing license and often contains a copy of the text of common open source licenses such as MIT , GPL or BSD .

Attention

It is necessary to place all the mentioned files and docs directory in the highest directory of the project directory.

docs : In this directory, project documents (help, training, etc.) are placed. The creation of these documents by Sphinx will be examined in a separate course.

test : This directory is where the project test program is stored. Creating a project test is also covered in a separate course. This directory can be placed both in the top branch of the project and inside the source code directory.

By creating a distribution from this structure and publishing it [which you will learn in the future], it is possible to install the project via pip. Usually the word “package” is used instead of the word “distribution”; As pip is also called “Python package management system” and it should never be confused with the concept of “package” that has been introduced before.

Create source code

You do not need any special programs or tools to create source code files (modules and scripts) and you can only create and edit them using a simple text editor (such as Notepad in Windows).

Next we create a project called FirstProject whose source code contains only one script. The task of this script will be to send the result of the expression 4÷(6×5-50)to the output (Output).

Run the default text editor of the operating system and use it to write one of the following code (suitable for your Python version) in a file with the same name as first_project and py extension and save it to disk (in the path of the operating system Documents directory) .

For version 2x, consider the structure of the FirstProject and the contents of the first_project_2x.py file as follows:

FirstProject
.
└── first_project_2x.py

#-*- coding: utf-8 -*-&amp;lt;/code&amp;gt;

# Python 2.x&amp;lt;/code&amp;gt;
# File Name: first_project_2x.py&amp;lt;/code&amp;gt;
# This script prints a value to the screen.&amp;lt;/code&amp;gt;

print "(50-5×6)÷4 =", (50-5*6)/4&amp;lt;/code&amp;gt;

And for version 3x, we consider the structure of the FirstProject and the content of the first_project_3x.py file as follows:

FirstProject
.
└── first_project_3x.py


# Python 3.x
# File Name: first_project_3x.py
# This script prints a value to the screen.

print("(50-5×6)÷4 =", (50-5*6)/4)

In the next section, we will run the FirstProject source code; In this section, it is better to examine its codes a little:

Python modules 2x default text of the Unicode standard ( Unicode ) are not supported by skiing ( ASCII ) coding (Encoding), which only allows the use of 128 characters. You can specify the coding method by adding a line according to the pattern at the beginning of the Python modules (first or second line). [ PEP 263 ]-*- coding: encoding -*-#

Accordingly, we changed the encoding of the first_script_2x.py script to UTF-8 due to the use of characters outside the ASCII set (÷ and ×). Python 3x supports the Unicode standard by default.

In the Python language, any text after the character “Number sign” or # (on the same line) is ignored by the Python interpreter and has no effect on the process of translating and executing the code. This type of text is called a “comment”. It is used to document the module, that is, to provide an explanation of part of the code. Explaining plays a big role in the readability of the module and helps other people – even yourself – to understand how your module code (or script) works.

Attention

The first character is also the expression of the coding determination #, but this line is not a comment and its understanding is valuable for the interpreter.

Blank Lines are also ignored by the Python interpreter and have no effect on the translation and execution of code. Proper use of blank lines increases the readability of module code.

A common way to send data to output (here: ‌ screen printing) in Python is to use a command print(in version 2x) or a function ()print(in version 3x). The most obvious difference between Python 3.0 and its predecessors is the conversion of the command printto a function. For the function, the data is enclosed in parentheses. [In a separate lesson we will look at functions in Python]

The print command (or function) has the ability to receive any number of data of any type, and if it receives an arithmetic or logical expression, it first calculates or evaluates the result and then converts it to a string data type in the output. puts. When sending several different data to the output, we have to separate them by Comma. Here, too, print receives two data to send to the output; A string data type and a computational expression.

A sequence of characters enclosed between two quotation marks is enclosed in a string.” “

Run source code

In general, code can be written and executed in Python in two ways: 1- Interactive mode with Python interpreter 2- By creating Python script.

Interactive method: In this method, you must first pythonenter the command to call the Python interpreter (general mode of the command 🙂 in the command line interface of the operating system; With this command, the command line enters the Python interactive mode and you can now simply start coding. In this case, any code that is entered is executed immediately and, if necessary, the result is displayed. Since it is not possible to return and edit the entered code in this method, it is not very efficient in practice, and even more so in cases such as getting small code snippet results, training goals, getting tips or calculators! is used. How to work with Python interactive mode will be explored in the next lesson.

user> python

Python 2.7.9 (default, Jan 12 2015, 12:41:47)

[GCC 4.9.2 20141101 (Red Hat 4.9.2-1)] on linux2

Type "help", "copyright", "credits" or "license" for more information.

>>>

>>> a = 3

>>> b = 2

>>> a * b

6

>>>

Another method that is the subject of this section is to create a script. We are already familiar with creating source code and scripts, and we know that scripts are modules that are developed to run source code, and executable source code always starts with the script.

To run the script, you must enter the command to call the Python interpreter along with the full name of the script (address + name + extension) on the command line of the operating system.

The following examples show the result of running the script in the previous section via the Gnolinux command-line interface.

user> python2 Documents/FirstProject/first_project_2x.py
(50-5×6)÷4 = 5

user> python3 Documents/FirstProject/first_project_3x.py
(50-5×6)÷4 = 5.0

If you pay attention to the result of the phrase 4÷(6×5-50)in the output of the two scripts, you must have noticed the difference. Python 2x calculates the result of dividing two integers as an integer and ignores the value after the dot (if any), but Python 3x always divides the result by a decimal number (Floating Point) accurately. It returns more. We will talk about this again.

The result of running these two scripts in each operating system is the same as you can see above. If you are a user of the Windows operating system, note that due to the presence of certain characters (÷ and ×) that are to be displayed by print on the command line, as well as the lack of default support of the Windows command line for UTF-8 encoding, An error related to Python code was reported while executing the script. In these cases, it is recommended to use Python 3x and PowerShell program and enter the command before executing the script – as follows:chcp 65001.

PS > chcp 65001
Active code page: 65001

PS > python Documents\FirstProject\first_script_3x.py
(50-5×6)÷4 = 5.0

How to run Python scripts is nothing more than that, but you can also send data as an argument when running scripts, which will be covered in the next lesson.

Usually in Gnolinux a line like the one below is added to the beginning of Python scripts (only in the first line), in this case there is no need to call the Python interpreter during the execution and only after changing the mode of the script to the execution mode ( With the chmod command ), run it as usual in Unix:

#!/usr/bin/env python3

envIs a Unix Shell command that finds the Python interpreter while executing the script and replaces its address. Instead of using it, you envcan write the address of the Python interpreter explicitly usr/bin/python3/!#, but in cases where the Python is installed separately (interpreter address in this case: usr / local / bin / python3 /), it does not work and causes failure. It is implemented.

Now for example if we make the first_script_2x.py script more complete to run on Gnolinux:


#!/usr/bin/env python
#-*- coding: utf-8 -*-

# Python 2.x
# File: first_project_2x.py
# This script prints a value to the screen.

print "(50-5×6)÷4 =", (50-5*6)/4

After switching mode, it can be implemented in the following two ways in GNU-Linux distributions:

user> chmod +x Documents/FirstProject/first_project_2x.py

user> Documents/FirstProject/first_project_2x.py
(50-5×6)÷4 = 5

user> cd Documents/FirstProject/

user> chmod +x first_project_2x.py

user> ./first_project_2x.py
(50-5×6)÷4 = 5

Attention

The symbol #! ( Shebang ) should not be confused with the comment symbol in Python (#).

Creating and executing Python scripts, as you can see, is very simple and does not depend on the existence of any special tools, but for Python, like any other widely used language, a large number of IDEs have been developed, which are introduced below. we will pay.

PyDev : A complete, free, open-source IDE for the Eclipse platform.
PyCharm : is a product of the amazing company JetBrains, which of course is the full version for sale, but the community version is free and open source, which has many special features and facilities. ( Compare versions )
NetBeans : A complete, open source, free IDE that has many fans. NetBeans does not support Python by default, and plug-ins must be installed. ( Installation guide page )

tip

Integrated development environment or IDE tools is said that in addition to a rich text editor, another highly functional features such as the debugger ( Debugger ) available to programmers.

Behind the scenes performance

When you run a script; First, the script and all the modules inserted in it are sent to the compiled bytecode and then the resulting bytecodes are sent to the virtual machine for interpretation in machine language and execution. What we call the Python interpreter (implementation of CPython) is actually a combination of a compiler and a virtual machine. The image below shows the process of executing Python code well.

The bytecode of each Python module is stored in a file with a pyc extension that is reminiscent of py Compiled. This file is stored in a subdirectory named __pycache__ within the same module directory and is named according to the module name and the version of the Python interpreter used (example: module.cpython-34.pyc). Python Interpreter will use this saved file to increase execution speed in the future; In such a way that in the next execution, if there is no change in the module code or the version of Python interpreter, the interpreter will re-compile the source code to bytecode by loading the bytecode file.

Attention

Python Interpreter saves the bytecode file to disk only for modules inserted in the script, and does not do so for scripts.

Bytecodes Source code that contains only one script is stored in memory.

Attention

When for any reason (eg lack of space) the Python interpreter is unable to save the bytecode file on the machine disk, the interpreter will store the bytecode in memory and there will be no problem running. Of course, the bytecode will be removed after the execution or abrupt disconnection of the power supply.

Attention

In versions prior to 3.2, the __pycache__ directory is not created and the bytecode file with a name equal to the module name is placed in the same directory (example: module.pyc). In this old way, in addition to the clutter between the files, it is not possible to distinguish between translating different versions of the Python interpreter.

You will learn interactive coding in the next lesson, but keep in mind that the Python interpreter treats the coding environment in this mode as a script.

Create a virtual environment

Consider the case where you need different versions of some libraries to create different projects; Then how do you install multiple versions of the same library in Python? For example, suppose we want to develop two websites; One of the new version (1.8) web framework Django ( Django ) and the other on an older version (0.96) of the work, but can not !; Because it is not possible to install both of these versions together in Python (site-packages directory). In this situation, the solution is to create virtual environments (Virtual Environments) for the development of the desired projects; An environment that isolates the development and execution of each Python project with all its dependencies from other projects. In the following, we will examine two common tools in this regard.

virtualenv

Here we use pip to install virtualenv . [ Refer to the previous lesson for more information ] – Before starting each installation, it is better to update pip; Follow these steps below in the GNU Linux operating system:

user> sudo pip install -U pip

[...]

Successfully installed pip[...]

user>

Install virtualenv:

user> sudo pip install virtualenv

[...]

Successfully installed virtualenv[...]

user>

Attention

If both versions are installed 2x or 3x on the operating system; It does not matter which version you install virtualenv with pip. Because it is possible to use it for other versions as well.

The command is now used to create a virtual environment , which means the address of the desired directory in which we want to create the virtual environment:virtualenv ENVENV.

 user> virtualenv Documents/SampleENV/

The above command creates a virtual environment in the /Documents/SampleENVoperating system path , based on the Python interpreter whose pip we used to install virtualenv, and if we want to create our virtual environment based on another existing version of Python, we need to use the python--address option. Specify its interpreter [ Help page ]:

 user> virtualenv --python=python2 ENV
 user> virtualenv --python=python3 ENV
 user> virtualenv --python=/opt/python3.3/bin/python ENV

In the code example above, versions 2.7 and 3.4 of Python are already installed on the operating system, and version 3.3 is installed by the user in the opt / python3.3 / path.

Another example for Windows users:

 > virtualenv --python=C:\Python25\python.exe Documents\SampleENV\

We can now access libraries, pip, site-packages directory, and dedicated interpreter in our project. Of course, before starting work with a virtual environment, we must activate(enable) it and after finishing work deactivate(disable it). Enabling here means setting the operating system Path variable on the interpreter of the desired virtual environment, which is disabled by disabling this situation.

 user> cd Documents/SampleENV/
user> source bin/activate
(SampleENV)$

 (SampleENV)$ deactivate
user>

In Windows:

 > cd Documents\SampleENV\
> Scripts\activate.bat

(SampleENV)>

(SampleENV)> deactivate.bat

>

pyvenv

In 3x versions of Python and from 3.3 onwards, a module called venv has been added to the standard Python library to create a virtual environment that can be used instead of installing virtualenv; For this purpose, the pyvenv command is used with a similar pattern .pyvenv ENV

In Gnolinox:

 user> pyvenv Documents/SampleENV/

user> cd Documents/SampleENV/
user> source bin/activate
(SampleENV)$

 (SampleENV)$ deactivate
user>