What is the best project structure for Python packaged applications?

What is the best project structure for Python packaged applications?

Reproduced from Stackoverflow:https://stackoverflow.com/questions/193161/what-is-the-best-project-structure-for-a-python-application

and http://www.cnblogs.com/alex3714/articles/5765046.html#3719169

Developing an end-user desktop application (not a Web page), what is the best project folder hierarchy?

The main features of the ideal project folder hierarchy are easy to maintain, friendly IDE, proper source control branch/merge, easy to build installation package.

Note the point:

1. Where Do you put the source?
2. Where Do you put application startup scripts?
3. Where do you put the IDE project cruft?
4. Where do you put the unit/acceptance tests?
5. Where Do you put Non-python data such as config files?
6. Where Do you put Non-python sources such as C + + for pyd/so binary extension modules?

project/# When you don't releases, you should include a version number suffix: Twisted-2.5.

|--bin/to store some executable files of the project, of course you can name and script/ so on.

| |--Project do not add any code to them unless you call and invoke one of the main functions defined elsewhere in the project.

|

|--project/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.

| |--test/(2) its sub-directory to tests/ store unit test code;

|   | |--__init__.py

|   | |--test_main.py

| |

| |--__init__.py

| |--main.py (3) The entrance of the program is best named main.py .

| |

|--docs/Store some documents.

| |--conf.py

| |--Abc.rst

|

|--setup.py installs, deploys, packages the scripts.

|--Requirements Storage Software dependent external Python package list

|--README Project documentation.

DO:

• Name the directory something related to your project. For example, if your project was named "Twisted", name the top-level directory for its source files Twisted. When you don't releases, you should include a version number suffix:twisted-2.5.
• Create a directory twisted/bin and put your executables there, if you had any. Don ' t give them a .py extension, even if they is Python source files. Don ' t put any code in them except an import of and call to a main function defined somewhere else in your projects. (Slight wrinkle:since on Windows, the interpreter are selected by the file extension, your Windows users actually do want The. py extension. So if you are want to add it. Unfortunately there ' s no easy distutils trick that I know of to automate this process. Considering that on POSIX the. py extension are a only a wart, whereas on Windows the lack are an actual bug, if your Userba SE includes Windows users, want to opt to just has the. py extension everywhere.)
• If your project is expressable as a single Python source file, then put it into the directory and name it something relate D to your project. For example, twisted/twisted.py. If you need multiple source files, create a package instead (twisted/twisted/, with an empty twisted/twisted/__init__.py) and place your source files in it. For example, twisted/twisted/internet.py.
• Put your unit tests in a sub-package of your package (note-this means, the single Python source file option above WA S a trick-you always need at least one other file for your unit tests). For example, twisted/twisted/test/. Of course, make it a-package with twisted/twisted/test/__init__.py. Place tests the files like twisted/twisted/test/test_internet.py.
• Add Twisted/readme and twisted/setup.py to explain and install your software, respectively, if you ' re feeling nice.

Don ' t:

• Put your source in a directory called Src or lib. This makes it hard-to-run without installing. Do not name the source directory src or lib. This can cause installation difficulties.
• Put your tests outside of your Python package. This makes it hard-to-run the tests against an installed version. Do not place the tests file outside of the Python package, which will cause problems running tests on the installed version.
• Create a package is only have a __init__.py and then put all your code into __init__.py. Just make a module instead of a, it's simpler. Do not create a package that has only one __init__, and put all the code in the package. Instead of creating a module instead of a package, creating a module management is simpler than creating a package.
• Try to come up and magical hacks to make Python able to import your module or package without have the user add the Dir Ectory containing it to their import path (either via PYTHONPATH or some other mechanism). You'll not correctly handle all cases and users would get angry at your when your software doesn ' t work in their Environment. Try to think of ways that Python can automatically import modules and packages from a project using Python paths or other mechanisms without requiring user settings to add directories to the import environment. If your software does not handle all the cases correctly, users will be very angry when your software does not work in their environment.

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.

setup.pyThese things can be automated to improve 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. 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.

README Project description file.

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.

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.

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 .

What is the best project structure for Python packaged applications?