对于一个python应用程序,最好的项目结构是什么?

What is the best project structure for a Python application?

假设您希望在Python中开发一个非普通的最终用户桌面(而不是Web)应用程序。构建项目文件夹层次结构的最佳方法是什么?

理想的特性是易于维护、IDE友好性、适用于源代码管理分支/合并以及易于生成安装包。

特别地:

  • 你把源头放在哪里?
  • 应用程序启动脚本放在哪里?
  • 你把IDE项目放在哪里了?
  • 你把单元/验收测试放在哪里?
  • 您将非python数据(如配置文件)放在哪里?
  • 在PyD/SO二进制扩展模块中,你把非Python源放在哪里呢?

  • 没什么大不了的。任何让你快乐的东西都会奏效。没有太多愚蠢的规则,因为Python项目可以很简单。

    • /scripts/bin用于这种命令行接口材料
    • 用于测试的/tests
    • 用于C语言库的/lib
    • /doc用于大多数文档
    • 用于epydoc生成的api文档的/apidoc

    顶层目录可以包含自述文件、配置文件和其他内容。

    困难的选择是是否使用/src树。Python在EDCOX1,6,EDCOX1,3,和EDCOX1,1,像Java或C都没有区别。

    由于一些人认为顶级的/src目录毫无意义,因此顶级目录可以是应用程序的顶级架构。

    • /foo
    • /bar
    • /baz

    我建议把所有这些放在"我的产品名称"目录下。因此,如果您正在编写一个名为quux的应用程序,那么包含所有这些内容的目录名为/quux

    那么,另一个项目的PYTHONPATH可以包括/path/to/quux/foo以重用QUUX.foo模块。

    在我的例子中,因为我使用了Komodo编辑,所以我的IDE CUFT是一个.kpf文件。实际上,我把它放在顶层的/quux目录中,并忽略了将它添加到SVN中。


    根据Jean-PaulCalderone的python项目文件系统结构:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    Project/
    |-- bin/
    |   |-- project
    |
    |-- project/
    |   |-- test/
    |   |   |-- __init__.py
    |   |   |-- test_main.py
    |   |  
    |   |-- __init__.py
    |   |-- main.py
    |
    |-- setup.py
    |-- README


    Jean-Paul Calderone的这篇博客文章通常是作为一个答案在Freenode上的python中给出的。

    Filesystem structure of a Python project

    Do:

    • name the directory something related to your project. For example, if your project is named"Twisted", name the top-level directory for its source files Twisted. When you do releases, you should include a version number suffix: Twisted-2.5.
    • create a directory Twisted/bin and put your executables there, if you have any. Don't give them a .py extension, even if they are 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 is selected by the file extension, your Windows users actually do want the .py extension. So, when you package for Windows, you may 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 is a only a wart, whereas on Windows the lack is an actual bug, if your userbase includes Windows users, you may want to opt to just have 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 related 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 that the single Python source file option above was 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 in 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.
    • put your tests outside of your Python package. This makes it hard to run the tests against an installed version.
    • create a package that only has a __init__.py and then put all your code into __init__.py. Just make a module instead of a package, it's simpler.
    • try to come up with magical hacks to make Python able to import your module or package without having the user add the directory containing it to their import path (either via PYTHONPATH or some other mechanism). You will not correctly handle all cases and users will get angry at you when your software doesn't work in their environment.


    以正确的方式查看open-sourcing一个python项目。

    我来摘录一下这篇优秀文章的项目布局部分:

    When setting up a project, the layout (or directory structure) is important to get right. A sensible layout means that potential contributors don't have to spend forever hunting for a piece of code; file locations are intuitive. Since we're dealing with an existing project, it means you'll probably need to move some stuff around.

    Let's start at the top. Most projects have a number of top-level files (like setup.py, README.md, requirements.txt, etc). There are then three directories that every project should have:

    • A docs directory containing project documentation
    • A directory named with the project's name which stores the actual Python package
    • A test directory in one of two places

      • Under the package directory containing test code and resources
      • As a stand-alone top level directory
        To get a better sense of how your files should be organized, here's a simplified snapshot of the layout for one of my projects, sandman:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    $ pwd
    ~/code/sandman
    $ tree
    .
    |- LICENSE
    |- README.md
    |- TODO.md
    |- docs
    |   |-- conf.py
    |   |-- generated
    |   |-- index.rst
    |   |-- installation.rst
    |   |-- modules.rst
    |   |-- quickstart.rst
    |   |-- sandman.rst
    |- requirements.txt
    |- sandman
    |   |-- __init__.py
    |   |-- exception.py
    |   |-- model.py
    |   |-- sandman.py
    |   |-- test
    |       |-- models.py
    |       |-- test_sandman.py
    |- setup.py

    As you can see, there are some top level files, a docs directory (generated is an empty directory where sphinx will put the generated documentation), a sandman directory, and a test directory under sandman.


    "python packaging authority"有一个sampleproject:

    https://github.com/pypa/sampleproject网站

    它是一个示例项目,作为Python打包用户指南关于打包和分发项目的教程的帮助而存在。


    尝试使用python_样板文件模板启动项目。它在很大程度上遵循了最佳实践(例如这里的那些),但更适合于您发现自己愿意在某个时刻将您的项目拆分为多个鸡蛋(相信我,除了最简单的项目之外,还有其他任何项目,您都愿意这样做)。一种常见的情况是,您必须使用其他人的库的本地修改版本)。

    • 你把源头放在哪里?

      • 对于相当大的项目来说,将源代码分成几个鸡蛋是有意义的。每个鸡蛋将作为一个单独的设置工具布局在PROJECT_ROOT/src/下。
    • 应用程序启动脚本放在哪里?

      • 理想的选择是将应用程序启动脚本注册为其中一个鸡蛋中的entry_point
    • 你把IDE项目放在哪里了?

      • 取决于IDE。他们中的许多人把他们的东西放在PROJECT_ROOT/.项目的根目录中,这很好。
    • 你把单元/验收测试放在哪里?

      • 每个鸡蛋都有一套单独的测试,保存在其PROJECT_ROOT/src//tests目录中。我个人更喜欢用py.test来运行它们。
    • 您将非python数据(如配置文件)放在哪里?

      • 这要看情况而定。可以有不同类型的非Python数据。
        • "资源",即必须打包在鸡蛋中的数据。这些数据进入相应的egg目录,在包名称空间的某个地方。可通过pkg_resources包使用。
        • "配置文件",即被视为项目源文件外部的非python文件,但必须在应用程序开始运行时用一些值初始化。在开发过程中,我更喜欢将这些文件保存在PROJECT_ROOT/config中。对于部署,可以有各种选项。在Windows上,可以使用%APP_DATA%//config,在Linux、/etc//opt//config上。
        • 生成的文件,即应用程序在执行期间可能创建或修改的文件。我希望在开发期间将它们保存在PROJECT_ROOT/var中,在Linux部署期间将它们保存在/var下。
    • 在PyD/SO二进制扩展模块中,你把非Python源放在哪里呢?
      • 进入PROJECT_ROOT/src//native

    文档通常会进入PROJECT_ROOT/docPROJECT_ROOT/src//doc(这取决于您是否将某些鸡蛋视为单独的大型项目)。一些额外的配置将出现在文件中,如PROJECT_ROOT/buildout.cfgPROJECT_ROOT/setup.cfg


    根据我的经验,这只是一个迭代的问题。把你的数据和代码放在你想去的地方。很可能,你还是错了。但是一旦你对事情的发展有了更好的了解,你就可以更好地做出这些猜测了。

    至于扩展源,我们在主干下有一个代码目录,其中包含一个用于Python的目录和一个用于各种其他语言的目录。就我个人而言,下次我更倾向于尝试将任何扩展代码放入自己的存储库中。

    有了这句话,我回到了我的出发点:不要把它做得太大。把它放在你觉得有用的地方。如果你发现一些不起作用的东西,它可以(也应该)被改变。


    使用a href="http://peak.telecommunity.com/devcenter/setuptools"rel="noreferrer">setuptools/a a中的package_data支持,非python数据最好捆绑在python模块中。我强烈推荐的是使用命名空间包创建多个项目可以使用的共享命名空间——很像在com.yourcompany.yourproject中把包放在一起的Java约定(并且能够共享一个EDCOX1×22的命名空间)。

    重新分支和合并,如果您使用足够好的源代码管理系统,它甚至可以通过renames处理合并;a href="http://www.bazaar-vcs.org/"rel="noreferrer">bazaar/a a特别擅长。

    与这里的其他答案相反,我是+1关于拥有一个src目录的顶级目录(旁边有doctest目录)。文档目录树的特定约定因您使用的内容而异;a href="http://sphinx.pocoo.org/"rel="noreferrer">sphinx/a a,例如,其QuickStart工具支持其自己的约定。

    请利用SETUPTOOLS和pkg_资源;这使得其他项目更容易依赖特定版本的代码(如果您使用package_data)。