What is the best project structure for a Python application? [closed]

python directory-structure organization project-structure

Closed. This question needs to be more focused. It is not currently accepting answers. Want to improve this question? Update the question so it focuses on one problem only by editing this post. Closed 5 years ago. Improve this question

Imagine that you want to develop a non-trivial end-user desktop (not web) application in Python. What is the best way to structure the project's folder hierarchy?

Desirable features are ease of maintenance, IDE-friendliness, suitability for source control branching/merging, and easy generation of install packages.

In particular:

Where do you put the source? Where do you put application startup scripts? Where do you put the IDE project cruft? Where do you put the unit/acceptance tests? Where do you put non-Python data such as config files? Where do you put non-Python sources such as C++ for pyd/so binary extension modules?

S.Lott

Doesn't too much matter. Whatever makes you happy will work. There aren't a lot of silly rules because Python projects can be simple.

/scripts or /bin for that kind of command-line interface stuff

/tests for your tests

/lib for your C-language libraries

/doc for most documentation

/apidoc for the Epydoc-generated API docs.

And the top-level directory can contain README's, Config's and whatnot.

The hard choice is whether or not to use a /src tree. Python doesn't have a distinction between /src, /lib, and /bin like Java or C has.

Since a top-level /src directory is seen by some as meaningless, your top-level directory can be the top-level architecture of your application.

/foo

/bar

/baz

I recommend putting all of this under the "name-of-my-product" directory. So, if you're writing an application named quux, the directory that contains all this stuff is named /quux.

Another project's PYTHONPATH, then, can include /path/to/quux/foo to reuse the QUUX.foo module.

In my case, since I use Komodo Edit, my IDE cuft is a single .KPF file. I actually put that in the top-level /quux directory, and omit adding it to SVN.

Any open source python projects you would recommend emulating their directory structure?

Look at Django for a good example.

I don't tend to consider Django a good example -- playing tricks with sys.path is an instant DQ in my book.

re "tricks": Django adds the parent of the root project folder to the sys.path, so that modules can be imported as either "from project.app.module import klass" or "from app.module import klass".

Oh, I love this trick and am using it now. I want to put the shared module in another directory, and I do not want to install module system-wide, nor do I want to ask people to modify PYTHONPATH manually. Unless people propose something better, I think this is actually the cleanest way to go.

Søren Løvborg

According to Jean-Paul Calderone's Filesystem structure of a Python project:

Project/
|-- bin/
|   |-- project
|
|-- project/
|   |-- test/
|   |   |-- __init__.py
|   |   |-- test_main.py
|   |   
|   |-- __init__.py
|   |-- main.py
|
|-- setup.py
|-- README

how does executable file in the bin folder reference the project module? (I don't think python syntax allows ../ in an include statement)

@ThorSummoner That only works when remaining inside a single package. For the relative import to work here you'd need an __init__.py file in both the bin folder and the Project top folder.

@ThorSummoner Simple. You install the package! (pip install -e /path/to/Project)

It would be awesome if someone would zip up a sample of this layout with hello.py and hello-test.py and make it available for us newbs.

@Bloke The core is the -e flag, which installs the package as an editable package, that is, installs it as links to the actual project folder. The executable can then just import project to have access to the module.

Community

This blog post by Jean-Paul Calderone is commonly given as an answer in #python on Freenode.

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.

This was exactly what I needed. "DONT 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." Good to know!

Confused about "put your source in a directory called src or lib. This makes it hard to run without installing.". What would be installed? Is it the dir name that causes the issue, or the fact that it is a subdir at all?

"This makes it hard to run without installing." -- that's the point

I find it ironical that the example uses Twisted as the project name, since the official Twisted library now uses a src layout, which contradicts the first "Don't" recommendation: "put your source in a directory called src or lib. This makes it hard to run without installing." This is the whole point (see Ionel Cristian Mărieș's article).

Do: "put your source in a directory called src or lib."

alfonx

Check out Open Sourcing a Python Project the Right Way.

Let me excerpt the project layout part of that excellent article:

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: $ 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.

I do this, but more so: I have a toplevel Makefile with an 'env' target that automates 'virtualenv env ; ./env/bin/pip install -r requirements.txt ; ./env/bin/python setup.py develop', and also usually a 'test' target that depends on env and also installs test dependencies and then runs py.test.

@pjz Could you please expand your idea? Are you talking about putting Makefile at the same level as setup.py? So if I understands you correctly make env automates creatating a new venv and install the packages into it... ?

@St.Antario exactly. As mentioned I generally also have a 'test' target to run the tests, and sometimes a 'release' target that looks at the current tag and builds a wheel and sends it to pypi.

In this structure, how does any file inside /code/sandman/sandman/ import something in /code/sandman/docs/? Say, I want to import config.py from sandman.py. How should I do that?

guettli

The "Python Packaging Authority" has a sampleproject:

https://github.com/pypa/sampleproject

It is a sample project that exists as an aid to the Python Packaging User Guide's Tutorial on Packaging and Distributing Projects.

+ trend towards root/src/* structure: github.com/pypa/sampleproject/commit/…

for project structure recs also see setuptools.readthedocs.io/_/downloads/en/latest/pdf

Maggyero

Try starting the project using the python_boilerplate template. It largely follows the best practices (e.g. those here), but is better suited in case you find yourself willing to split your project into more than one egg at some point (and believe me, with anything but the simplest projects, you will. One common situation is where you have to use a locally-modified version of someone else's library).

Where do you put the source? For decently large projects it makes sense to split the source into several eggs. Each egg would go as a separate setuptools-layout under PROJECT_ROOT/src/.

For decently large projects it makes sense to split the source into several eggs. Each egg would go as a separate setuptools-layout under PROJECT_ROOT/src/.

Where do you put application startup scripts? The ideal option is to have application startup script registered as an entry_point in one of the eggs.

The ideal option is to have application startup script registered as an entry_point in one of the eggs.

Where do you put the IDE project cruft? Depends on the IDE. Many of them keep their stuff in PROJECT_ROOT/. in the root of the project, and this is fine.

Depends on the IDE. Many of them keep their stuff in PROJECT_ROOT/. in the root of the project, and this is fine.

Where do you put the unit/acceptance tests? Each egg has a separate set of tests, kept in its PROJECT_ROOT/src//tests directory. I personally prefer to use py.test to run them.

Each egg has a separate set of tests, kept in its PROJECT_ROOT/src//tests directory. I personally prefer to use py.test to run them.

Where do you put non-Python data such as config files? It depends. There can be different types of non-Python data. "Resources", i.e. data that must be packaged within an egg. This data goes into the corresponding egg directory, somewhere within package namespace. It can be used via the pkg_resources package from setuptools, or since Python 3.7 via the importlib.resources module from the standard library. "Config-files", i.e. non-Python files that are to be regarded as external to the project source files, but have to be initialized with some values when application starts running. During development I prefer to keep such files in PROJECT_ROOT/config. For deployment there can be various options. On Windows one can use %APP_DATA%//config, on Linux, /etc/ or /opt//config. Generated files, i.e. files that may be created or modified by the application during execution. I would prefer to keep them in PROJECT_ROOT/var during development, and under /var during Linux deployment.

It depends. There can be different types of non-Python data. "Resources", i.e. data that must be packaged within an egg. This data goes into the corresponding egg directory, somewhere within package namespace. It can be used via the pkg_resources package from setuptools, or since Python 3.7 via the importlib.resources module from the standard library. "Config-files", i.e. non-Python files that are to be regarded as external to the project source files, but have to be initialized with some values when application starts running. During development I prefer to keep such files in PROJECT_ROOT/config. For deployment there can be various options. On Windows one can use %APP_DATA%//config, on Linux, /etc/ or /opt//config. Generated files, i.e. files that may be created or modified by the application during execution. I would prefer to keep them in PROJECT_ROOT/var during development, and under /var during Linux deployment.

"Resources", i.e. data that must be packaged within an egg. This data goes into the corresponding egg directory, somewhere within package namespace. It can be used via the pkg_resources package from setuptools, or since Python 3.7 via the importlib.resources module from the standard library.

"Config-files", i.e. non-Python files that are to be regarded as external to the project source files, but have to be initialized with some values when application starts running. During development I prefer to keep such files in PROJECT_ROOT/config. For deployment there can be various options. On Windows one can use %APP_DATA%//config, on Linux, /etc/ or /opt//config.

Generated files, i.e. files that may be created or modified by the application during execution. I would prefer to keep them in PROJECT_ROOT/var during development, and under /var during Linux deployment.

Where do you put non-Python sources such as C++ for pyd/so binary extension modules? Into PROJECT_ROOT/src//native

Into PROJECT_ROOT/src//native

Documentation would typically go into PROJECT_ROOT/doc or PROJECT_ROOT/src/<egg_name>/doc (this depends on whether you regard some of the eggs to be a separate large projects). Some additional configuration will be in files like PROJECT_ROOT/buildout.cfg and PROJECT_ROOT/setup.cfg.

Thanks for a great answer! You clarified many things for me! I just have one question: Can eggs be nested?

No, you can't "nest" eggs in the sense of storing .egg files within other .egg files and hoping this would be of much use [unless you're up to something really weird]. What you can do, though, is create "virtual" eggs - empty packages that do not provide any useful code, but list other packages in their dependency lists. This way, when a user attempts to install such a package he will recursively install many dependent eggs.

@KT can you elaborate a bit about how you handle generated data? In particular, how do you (in code) distinguish between development and deployment? I imagine you have some base_data_location variable, but how do you set it appropriately?

I presume you are speaking about "runtime data" - something people would often put under /var/packagename or ~/.packagename/var, or whatnot. Most of the time those choices are sufficient as a default that your users don't care to change. If you want to allow this behaviour to be tuned, options are rather abundant and I do not think there is a single fits-all best practice. Typical choices: a) ~/.packagename/configfile, b) export MY_PACKAGE_CONFIG=/path/to/configfile c) command-line options or function parameters d) combination of those.

Note that it is quite usual to have a singleton Config class somewhere, which handles your favourite config loading logic for you and perhaps even lets the user modify the settings at runtime. In general, though, I think this is an issue worth a separate question (which might have been asked before somewhere here).

Jason Baker

In my experience, it's just a matter of iteration. Put your data and code wherever you think they go. Chances are, you'll be wrong anyway. But once you get a better idea of exactly how things are going to shape up, you're in a much better position to make these kinds of guesses.

As far as extension sources, we have a Code directory under trunk that contains a directory for python and a directory for various other languages. Personally, I'm more inclined to try putting any extension code into its own repository next time around.

With that said, I go back to my initial point: don't make too big a deal out of it. Put it somewhere that seems to work for you. If you find something that doesn't work, it can (and should) be changed.

Yep. I try to be "Pythonic" about it: explicit is better than implicit.. Directory heirarchies are read/inspected more than they are written. Etc..

Charles Duffy

Non-python data is best bundled inside your Python modules using the package_data support in setuptools. One thing I strongly recommend is using namespace packages to create shared namespaces which multiple projects can use -- much like the Java convention of putting packages in com.yourcompany.yourproject (and being able to have a shared com.yourcompany.utils namespace).

Re branching and merging, if you use a good enough source control system it will handle merges even through renames; Bazaar is particularly good at this.

Contrary to some other answers here, I'm +1 on having a src directory top-level (with doc and test directories alongside). Specific conventions for documentation directory trees will vary depending on what you're using; Sphinx, for instance, has its own conventions which its quickstart tool supports.

Please, please leverage setuptools and pkg_resources; this makes it much easier for other projects to rely on specific versions of your code (and for multiple versions to be simultaneously installed with different non-code files, if you're using package_data).

What is the best project structure for a Python application? [closed]

Follow WeChat

Want to stay one step ahead of the latest teleworks?

相似问题

Platform

Support

Contact US