python--Software directory structure

Software Catalog Structure specification

Design Directory Structure Advantages:

1. High readability, can quickly understand the project

2. With high maintainability and defined organizational rules, the maintainer will be able to clearly know which file and code should be placed under what directory.

How directory is organized

foo/
|--bin/
| |--Foo
|
|--foo/
| |--tests/
|   | |--__init__.py
|   | |--test_main.py
| |
| |--__init__.py
| |--main.py
|
|--docs/
| |--conf.py
| |--Abc.rst
|
|--setup.py
|--Requirements.txt
|--README

Briefly explain:

1. bin/: Store some executable files of the project, of course you can name and script/ so on.
2. foo/: stores 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 preferably named main.py .
3. docs/: Store some documents.
4. setup.py: Install, deploy, and package the scripts.
5. requirements.txt: A list of external Python packages that store software dependencies.
6. README: Project description file.

In addition, there are a number of scenarios that give more content. For example LICENSE.txt , ChangeLog.txt files and so on, I am not listed here, because these things are mainly open source projects need to use. If you want to write an open source software, how to organize the directory, you can refer to this article.

Now, let me briefly explain my understanding of these directories and my personal requirements.

About the content of the Readme

The goal is to briefly describe the project's information so that the reader can quickly understand the project.

It needs to illustrate several things:

1. Software positioning, the basic functions of the software.
2. How to run your code: Installation environment, startup commands, and so on.
3. Brief instructions for use.
4. Code directory structure Description, more detailed can explain the basic principles of the software.
5. FAQ's description.

can refer to the Redis source code in the wording of the readme, which is concise but clearly describes the Redis function and source structure.

About Requirements.txt and setup.pysetup.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.

Problem:

1. Install the environment often forget that recently added a new Python package, the result of running on the line, the program is wrong.
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.pyThese things can be automated to improve efficiency and reduce the probability of errors.

Setuptools documents are huge, just contact, it may not be very good to find an entry point. The way to learn technology is to see how others are used, you can refer to a Python web framework, How flask is written: setup.py

Of course, simply writing a setup script ( deploy.sh ) setup.py can be an alternative.

Requirements.txt

The purpose of this file exists is to:

1. Easy for developers to maintain software package dependencies. Add the new packages in the development process to this list to avoid setup.py missing packages when installing dependencies.
2. Make it easy for readers to identify which Python packages the project uses.

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

about how to use the configuration file note that in the above directory structure, there is no conf.pyPlaced in the source directory, but placed in 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.

Disadvantages:

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.

Configuration of the use, 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 .

Take the ATM project as an example directory structure:

The main code main.py needs to be called through the atm.py file in the project, implemented as follows:

#writing code in the main filedeflogin ():Print("Welcome .")#Configure environment Variables step#The path of your program returns the relative path of the current programPrint(__file__)ImportOS#return Absolute PathPrint(Os.path.abspath (__file__))#back to previous levelPrint(Os.path.dirname (Os.path.abspath (__file__)))#and then back to the upper levelPrint(Os.path.dirname (Os.path.dirname (Os.path.abspath (__file__))))#Assign ValueImportSysbase_dir= Os.path.dirname (Os.path.dirname (Os.path.abspath (__file__)))#Adding environment Variablessys.path.append (Base_dir)#Import Conf,core fromConfImportSettings fromCoreImportMainmain.login ()#finally calls the code in the ATMImportSys,osbase_dir= Os.path.dirname (Os.path.dirname (Os.path.abspath (__file__)))#Adding environment Variablessys.path.append (Base_dir) fromConfImportSettings fromCoreImportMainmain.login ()

python--Software directory structure