Почему некоторые пакеты Python имеют повторяющиеся имена каталогов?

Question

Вопрос о том, что структура каталогов проекта Python был задан несколько раз при переполнении стека (например, здесь, здесь и здесь)

И много ответов дано. Но одна вещь, которая, кажется, не ясна ни в одном из этих ответов, - это то, почему некоторые проекты имеют повторяющиеся каталоги. Например, в этой статье, которая часто цитируется, предлагается макет:

<root>/
|-- Twisted/    
|   |-- __init__.py
|   |-- README
|   |-- setup.py
|   |-- twisted/ 
|   |   |-- __init__.py
|   |   |-- main.py
|   |   |-- test/   
|   |   |   |-- __init__.py
|   |   |   |-- test_main.py
|   |   |   |-- test_other.py
|   |   |-- bin/
|   |   |   |-- myprogram

В этом примере /Twisted/twisted/main.py это основной файл

Но с другой стороны, у вас есть такой совет:

Многие разработчики плохо структурируют свои репозитории из-за новых шаблонов приложений в комплекте.

<root>/
|-- samplesite/
|   |-- manage.py  
|   |-- samplesite/
|   |   |-- settings.py
|   |   |-- wsgi.py   
|   |   |-- sampleapp/
|   |   |-- models.py

Не делай этого.

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

<root>/
|-- manage.py  
|-- samplesite/
|   |-- settings.py
|   |-- wsgi.py   
|   |-- sampleapp/
|   |-- models.py

Мой вопрос не обязательно "какой путь лучше?", Поскольку у каждого способа могут быть плюсы или минусы.

Вместо этого, мой вопрос: что я потеряю, если я выберу второй упрощенный стиль? Есть ли веская причина иметь /<root>/Twisted/twisted/main.py структура каталога, а не просто /<root>/twisted/main.py? Облегчает ли как-то поделиться моим приложением или сделать import процесс плавнее? Что-то другое?

Answer 1

Эти два документа ближе, чем вы думаете. И Интересные вещи, и в основном Python, и Twisted Related (ваш первый пример), и документы django-admin startproject предполагают, что вы находитесь за пределами репозитория проекта, в то время как Структурирование вашего проекта (ваш второй пример) предполагает, что вы находитесь внутри репозитория. Процитируем: "Ну, они идут в свой чистый и свежий репозиторий и запускают следующее...".

В документации Django говорится, что если вы запустите

django-admin.py start-project samplesite 

И каталог проекта, и пакет проекта будут названы, а каталог проекта будет создан в текущем рабочем каталоге.

Команда создает каталог проекта для вас, так что вы, конечно, не должны находиться внутри уже созданного каталога проекта, когда вы его запускаете. Документы продолжают говорить

django-admin startproject myproject /Users/jezdez/Code/myproject_repo 

Если указан дополнительный пункт назначения, Django будет использовать этот существующий каталог в качестве каталога проекта.

Теперь предположим, что вы уже /Users/jezdez/Code/myproject_repo, Тогда вы бы сделали

django-admin startproject myproject .

создать пакет проекта в текущем каталоге. Вуаля, у вас есть второй авторский пример! Автор на самом деле просто говорил вам избегать первой формы, если вы создаете репозиторий перед запуском команды.

Итак, давайте перерисовать вашу структуру каталогов. В первом примере <root> каталог, в котором вы храните свои репозитории Twisted каталог с вашим репо (Кроме того, этот каталог не должен иметь __init__.py потому что это не каталог пакетов). В последнем примере <root> это сам каталог репо. Предположим, я назвал этот каталог DjangoExample, тогда структура будет

<root>
|-- Twisted/    
|   |-- __init__.py
|   |-- README
|   |-- setup.py
|   |-- twisted/ 
|   |   |-- __init__.py
|   |   |-- main.py
|   |   |-- test/   
|   |   |   |-- __init__.py
|   |   |   |-- test_main.py
|   |   |   |-- test_other.py
|   |   |-- bin/
|   |   |   |-- myprogram
|
|-- DjangoExample/
|   |-- manage.py  
|   |-- samplesite/
|   |   |-- settings.py
|   |   |-- wsgi.py   
|   |   |-- sampleapp/
|   |   |-- models.py

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

Answer 2

Я считаю, что наиболее распространенная схема проектов Python выглядит примерно так:

project/
|-- setup.py
|-- bin/
|-- docs/ ...
|-- examples/ ...
|-- package/
    |-- __init__.py
    |-- module1.py
    |-- module2.py
    |-- subpackage/ ...
    |-- tests/ ...

Где проект - это имя проекта, а пакет - имя импорта верхнего уровня, например, scikits-learn и sklearn. Пакет содержит все, что Python должен быть в состоянии импортировать, и вы импортируете, используя имя пакета. Например from package import thing или же from package.module1 import thing, У проекта есть пакет и все вспомогательные средства, такие как документы, примеры и установочные скрипты. Обратите внимание, что обычно нет __init__.py в проекте, потому что проект не является импортируемым Python. Обычно проект и пакет имеют одно и то же имя, но не обязательно.