Python Learning Path: Software Catalog Development Specification

I. Background

Software development is a system engineering, of course, the implementation of coding is one of the most important link, related to the realization of functional requirements or good or bad. This link in addition to coding this hard training, the relevant coding style of this judo, although not directly determine the implementation of the function or not, but to a large extent determines the overall project code readability, robustness, portability, maintainability and other important features. The coding style involves not only how the code is written, but also the distribution organization of the code module, the design of the project code directory.

Good code directory design can visually show the logic of the developers, improve the readability of code, maintainability, portability and even robustness, bad code directory design is not elaborate, the logic level confusion, code copy to other environments can not run, etc. is the most common problem.

Talk about software catalog development and design specifications today.

second, the importance and necessity of the design software catalogue development Norm

In the above mentioned a little mention of the software project code catalog design specifications on the project some of the impact, here the elaboration of its importance and necessity, roughly the following points:

• High readability: A good code catalog design allows people who are just in touch with the project to get an overview of the developer's logic, clear the location of the program's entry file, test sample, description of the Help document, configuration file, and so on, so you can familiarize yourself with the project as quickly as possible.
• Strong maintainability: The current directory design specification can clearly prompt the maintainer of new code files, configuration files, and so on which directory the design, in order to better maintain the project. This ensures that the maintainability of the project itself remains strong over time and as people change.
• Portability: When a project is on a scale or becomes complex, it is extremely important to distribute files of different purposes through different levels of catalogs, which ensures that the code package is copied to other environments, avoiding failures due to module dependencies, missing configuration files, failed directory calls, and so on.

Third, the Software Development directory organization Way

Just take python, for example, to discuss the proposed Software development catalog organization structure:

Foo/|-- bin/|   |-- foo||-- foo/|   |-- tests/|   |   |-- __init__.py|   |   |-- test_main.py|   ||   |-- __init__.py|   |-- main.py| |--conf/ |  __init__.py |　|-- settings.py | |--logs/ ||-- docs/|   |-- conf.py|   |-- abc.rst||-- setup.py|-- requirements.txt|-- README

The explanations are as follows:

1. bin/: To store some executable files of the project, of course the name scripts/and so on.

2. foo/: Store all source code for the project. (1) All modules and packages in the source code should be placed in this directory. Do not place the top level directory. (2) Its subdirectory tests/ holds unit test code, and (3) The entrance of the program is best       named main.py .

3. conf/: Store configuration file

4. logs/: Various logs generated as log directory store program run

5. docs/:存放项目的帮助文档

6. setup.py：安装、部署、打包的脚本，一般用于适配环境、解决依赖关系等

7. requirements.txt: 存放软件依赖的外部python包列表

8. README：存放项目说明文档，下文详述

除此之外，有一些方案给出了更加多的内容。比如LICENSE.txt,ChangeLog.txt文件等，其中LICENSE.txt主要是项目开源的时候需要用到。ChangeLog.txt可根据需要确定是否添加。

Four, the Readme related

The use of open source software friends know that the Readme can bring great help to the use of software, including the introduction of software, functional positioning, installation of the use of start-up methods, suggestions or bug how to contact the author, the necessity and importance of self-evident.

Therefore, each project should have a readme description, good readme should include at least the following aspects of the content:

• Brief introduction of software, function positioning, application scenarios, etc.
• Software installation, environmental dependencies, startup methods, common use commands (instructions for use), etc.
• Directory structure description of the code
• FAQ description
• Encounter suggestions or bugs how to contact an author or project group

If you write more details, you can consider outlining the fundamentals of the software. The best reference in this regard is the readme of open source software, such as Nginx,redis.

v. Requirements.txt and setup.py related1. Requirements

Requirements mainly addresses the following two issues:

1. The convenience of the developer to maintain the package relies on the new dependency package generated when added directly to the list, and then through the setup.py automatically resolve the dependency, to avoid missing
2. User-friendly explicit dependencies

The format of Requirements.txt is that each line contains a description of the package dependency, usually flask>=0.10 this format, which requires that the format be pip recognized, so that you can simply pass pip install -r requirements.txt all the Python package dependencies are installed. Specific format description: Punch here.

2.setup.py

In general, use it setup.py to manage the packaging, installation, and deployment of your code. The industry standard notation is to use Python's popular packaging tools Setuptools to manage these things. This approach is commonly used in open source projects. But the core idea here is not to use standardized tools to solve these problems, but to say that a project must have an installation deployment tool that can quickly and easily install the environment on a new machine, deploy the code, and run the program.

This problem is like installing a software on Linux with Yum, and we have to admit that Yum installation is easier to install than source code to solve environmental dependencies.

In the case of Python projects, many have experienced the following problems for beginners:

1. When installing the environment, I forgot to add a new Python package recently, and the program went wrong as soon as it ran on the line.
2. Python package version dependencies, sometimes we use a version of the Python package, but the official is already the latest package, by manual installation may be wrong.
3. If you rely on a lot of packages, it is time-consuming to install these dependencies one by one.
4. When a new classmate starts writing a project, it is very troublesome to run the program because it may often forget how to install various dependencies.

setup.py的目的是Automate these things, unify automated management, increase efficiency and reduce the probability of errors. "Complex things are automated and things that can be automated must be automated. "is a very good habit.

Setuptools documents are huge, just contact, it may not be very good to find an entry point. Let's start with imitation, you can refer to a Python web framework, How flask is written: setup.py

If you're developing a project that's just running on a Linux environment, simply write your own installation script ( deploy.sh ) instead setup.py .

vi. configuration file relatedNote that in the above directory structure, it will not be conf.py placed in the source directory, but in the docs/ directory.

Many projects use the configuration file as follows:

1. The configuration file is written in one or more Python files, such as the conf.py here.
2. Which module in the project uses this configuration file directly import conf in this form to use the configuration in the code.

I don't quite agree with this approach:

1. This makes unit testing difficult (because the module internally relies on external configuration)
2. On the other hand, the configuration file as the interface of the user control program, should be free to specify the path of the file.
3. The reusability of the program components is too poor, because the code is hardcoded across all modules, making most modules dependent on conf.py the file.

So, I think the use of configuration, the better way is that

1. The configuration of the module is flexible and is not affected by external configuration files.
2. The configuration of the program can also be flexibly controlled.

Can support this idea is, with Nginx and MySQL students know that nginx, MySQL these programs are free to specify the user configuration.

Therefore, you should not use the configuration file directly in your code import conf . In the above directory structure conf.py , is a configuration sample given, not to write dead in the program directly referenced by the configuration file. You can main.py let the program read the configuration by specifying the configuration path for the startup parameter. Of course, conf.py You can change a similar name here, for example settings.py . Or you can use other formats to write configuration files, such as settings.yaml .

-------------------------atm.py-------------------------------Print (__file__) #返回当前程序的相对路径import Osimport Sysprint (Os.path.abspath (__file__)) #返回绝对路径print (Os.path.dirname (Os.path.abspath (__file__))) #返回上级路径BASE_DIR = Os.path.dirname (Os.path.dirname (Os.path.abspath (__file__))) Sys.path.append ((Base_dir)) from conf import Settingsfrom Core Import mainmain.login ()--------------------------- main.py------------------------------------def login ():    print ("Welcome to my ATM")

Python Learning Path: Software Catalog Development Specification