Какая структура проекта лучше всего подходит для приложения Python?

Не имеет большого значения. Все, что делает вас счастливым, будет работать. Глупых правил не так много, потому что проекты Python могут быть простыми.

• /scripts или /bin для такого рода интерфейсов командной строки
• /tests для ваших тестов
• /lib для ваших библиотек на языке C
• /doc для большей части документации
• /apidoc для документации API, созданной Epydoc.

А каталог верхнего уровня может содержать README, Config и еще много чего.

Трудный выбор - использовать дерево /src или нет. Python не делает различий между /src, /lib и /bin, как Java или C.

Поскольку каталог /src верхнего уровня рассматривается некоторыми как бессмысленный, каталог верхнего уровня может быть архитектурой верхнего уровня вашего приложения.

• /foo
• /bar
• /baz

Я рекомендую поместить все это в каталог «name-of-my-product». Итак, если вы пишете приложение с именем quux, каталог, содержащий все это, называется /quux.

Таким образом, PYTHONPATH другого проекта может включать /path/to/quux/foo для повторного использования модуля QUUX.foo.

В моем случае, поскольку я использую Komodo Edit, моя IDE cuft представляет собой один файл .KPF. На самом деле я помещаю это в каталог /quux верхнего уровня и не добавляю его в SVN.

Данные, отличные от Python, лучше всего объединять внутри ваших модулей Python с помощью поддержки package_data в setuptools. Одна вещь, которую я настоятельно рекомендую, - это использовать пакеты пространств имен для создания общих пространств имен, которые могут использовать несколько проектов - во многом подобно соглашению Java о размещении пакетов в com.yourcompany.yourproject (и возможности иметь общее пространство имен com.yourcompany.utils).

Что касается ветвления и слияния, если вы используете достаточно хорошую систему управления версиями, она будет обрабатывать слияния даже при переименовании; Базар особенно хорош в этом.

В отличие от некоторых других ответов здесь, я +1 к каталогу верхнего уровня src (вместе с каталогами doc и test). Конкретные соглашения для деревьев каталогов документации будут различаться в зависимости от того, что вы используете; Например, Сфинкс имеет свои собственные соглашения, которые поддерживает его инструмент быстрого запуска.

Пожалуйста, используйте setuptools и pkg_resources; это упрощает другим проектам использование определенных версий вашего кода (и одновременную установку нескольких версий с разными файлами, не являющимися файлами кода, если вы используете package_data).

По моему опыту, это просто вопрос повторения. Поместите свои данные и код туда, где, по вашему мнению, они находятся. Скорее всего, вы все равно ошибетесь. Но как только вы получите лучшее представление о том, как именно будут развиваться события, вы будете в гораздо лучшем положении, чтобы делать такие предположения.

Что касается источников расширений, у нас есть каталог кода в основной строке, который содержит каталог для python и каталог для различных других языков. Лично я более склонен в следующий раз попытаться поместить любой код расширения в его собственный репозиторий.

Сказав это, я возвращаюсь к своей исходной точке: не придавайте этому большого значения. Положите его туда, где вам кажется, что это работает. Если вы обнаружите, что что-то не работает, это можно (и нужно) изменить.

Этот сообщение в блоге Жана-Поля Кальдерона обычно задается как ответ в #python на 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.

Согласно Структура файловой системы проекта Python Жан-Поля Кальдероне:

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

Проверьте Открытый исходный код проекта 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:

$ 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_boilerplate. Он в значительной степени соответствует передовым методам (например, те, кто здесь), но лучше подходит в том случае, если вы обнаружите, что в какой-то момент захотите разделить свой проект на более чем одно яйцо (и поверьте мне, с любыми проектами, кроме простейших, вы это сделаете. ситуация, когда вам нужно использовать локально измененную версию чужой библиотеки).

• Куда вы положили источник?

  • Для прилично больших проектов имеет смысл разбить исходник на несколько яиц. Каждое яйцо будет идти как отдельный макет setuptools под PROJECT_ROOT/src/<egg_name>.

• Куда вы кладете скрипты запуска приложений?

  • Идеальный вариант - зарегистрировать сценарий запуска приложения как entry_point в одном из яиц.

• Куда вы положили хлам проекта IDE?

  • Зависит от IDE. Многие из них хранят свои данные в PROJECT_ROOT/.<something> в корне проекта, и это нормально.

• Где вы ставите модульные / приемочные испытания?

  • Каждое яйцо имеет отдельный набор тестов, хранящийся в каталоге PROJECT_ROOT/src/<egg_name>/tests. Я лично предпочитаю использовать py.test для их запуска.

• Куда вы помещаете данные, не относящиеся к Python, например файлы конфигурации?

  • По-разному. Могут быть разные типы данных, отличных от Python.
    • "Ресурсы", т.е. данные, которые должны быть упакованы в яйцо. Эти данные попадают в соответствующий каталог egg где-нибудь в пространстве имен пакета. Его можно использовать через пакет pkg_resources из setuptools или, начиная с Python 3.7, через модуль importlib.resources из стандартной библиотеки.
    • "Конфиг-файлы", то есть файлы, отличные от Python, которые должны рассматриваться как внешние по отношению к исходным файлам проекта, но должны быть инициализированы некоторыми значениями при запуске приложения. Во время разработки я предпочитаю хранить такие файлы в PROJECT_ROOT/config. Для развертывания могут быть разные варианты. В Windows можно использовать %APP_DATA%/<app-name>/config, в Linux - /etc/<app-name> или /opt/<app-name>/config.
    • Сгенерированные файлы, то есть файлы, которые могут быть созданы или изменены приложением во время выполнения. Я бы предпочел оставить их в PROJECT_ROOT/var во время разработки и в /var во время развертывания Linux.
• Где вы размещаете источники, отличные от Python, такие как C++ для модулей двоичного расширения pyd / so?
  • В PROJECT_ROOT/src/<egg_name>/native

Документация обычно идет в PROJECT_ROOT/doc или PROJECT_ROOT/src/<egg_name>/doc (это зависит от того, рассматриваете ли вы некоторые из яиц как отдельные большие проекты). Некоторая дополнительная конфигурация будет в файлах типа PROJECT_ROOT/buildout.cfg и PROJECT_ROOT/setup.cfg.

У "Python Packaging Authority" есть образец проекта:

https://github.com/pypa/sampleproject

Это образец проекта, который существует как помощь в Руководстве пользователя Python Packaging Tutorial on Packaging and Distributing Projects.