Существуют ли правила для именования одномодульных пакетов Python?

Должно ли имя, которое я передаю одинокому модулю в пакете Python, соответствует имени пакета?

Например, если у меня есть пакет с одним модулем со структурой

super-duper/
    super/
        __init.py___
        mycode.py
        ...

Я могу создать пакет super-duper на PyPi, который при установке будет иметь две папки в site-packages с именами, которые не совпадают:

 super/
 super_duper-1.2.3.dist-info/

что означает, что для импорта моего проекта я использую

import super

а не фактическое имя пакета (super_duper)

Это, по-видимому, противоречит обычной практике (судя по папкам для раннего каждого другого пакета, который я вижу в site-packages), которые следуют шаблону

 same_name/
 same_name-1.2.3.dist-info/

для пакета PyPi same-name.

Должен ли я (всегда) структурировать свои проекты так, чтобы

super-duper/
    super_duper/
        __init.py___
        mycode.py
        ...

чтобы имя пакета и имя импорта модуля совпадали:

import super_duper

Есть ли соответствующая передовая практика или правило, которым я должен следовать?

Ответ 1

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

Несколько более длинный ответ заключается в том, что соглашения об именах всегда являются политическими. Общепринятым методом определения языковых стандартов в Python является процесс под названием "Предложения по улучшению Python" (PEP). PEP управляются органом редакторов PEP и публично проиндексированы для просмотра и комментирования.

В настоящее время существует только один "активный" (принятый и реализованный) PEP, о котором я знаю, охватывает соглашения об именах модулей, которые являются PEP 8:

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

Тем не менее, еще есть еще одно предложение в процессе разработки, называемое PEP 423, которое рекомендует именно то, что вы указываете в своем сообщении:

Распространять только один пакет (или только один модуль) на один проект и использовать имя пакета (или модуля) в качестве имени проекта.

Это позволяет избежать возможной путаницы между именем проекта и распределенным именем пакета или модуля.

Он делает имя согласованным.

Явно: когда вы видите имя проекта, он угадывает имя пакета/модуля и наоборот.

Он также ограничивает неявные столкновения между именами пакетов/модулей. Используя одно имя, когда вы регистрируете имя проекта в PyPI, вы также выполняют проверку доступности базового пакета/модуля.

Важно отметить, что этот PEP по-прежнему находится в состоянии "Отложенное", что означает, что он не был ратифицирован редакторами PEP и заблокирован другим предложением (в частности, реализация обновления для синтаксиса метаданных модуля в PEP 440). Тем не менее, никакие конкурирующие стандарты не были разработаны в то время, так как 423 первоначального предложения, и большая часть содержания, кажется, довольно бесспорный, так что я бы ожидать, что она будет принята в будущем, не слишком много существенных изменений.

Ответ 2

Нет никаких рекомендаций, которые мне известны, для чего требуется, чтобы имя вашего проекта соответствовало установленному пакету или модулю. Существует отложенный проект PEP-423 Соглашения об именах и рецепты, связанные с упаковкой, но это фактически отменено (a ожидающее обновления никогда не применялось).

Вы говорите, что посмотрели, но вы, вероятно, пропустили некоторые существующие примеры, в которых не указаны имя проекта и пакет:

Проект BeautifulSoup использует beautifulsoup4 для имени проекта в PyPI, который устанавливает пакет bs4.
dateutil Пакет Python доступен в PyPI как python-dateutil. Префикс имен проектов PyPI с python- является довольно распространенным я сегодня подсчитал 1512 таких пакетов на PyPI.
Проект Viivakoodi является вилкой pyBarcode. Проект viivakoodi PyPI устанавливает пакет barcode в site-packages. Другой такой проект fork Pillow, который является вилкой библиотеки изображений Python. Он доступен в PyPI под этим именем, но пакет устанавливает пакет PIL.

Тем не менее, лично я предпочитаю его для имени проекта PyPI и пакета, содержащегося для соответствия; это уменьшает путаницу. Наиболее заметным исключением является проектная вилка, целью которой является сохранение старого имени пакета для облегчения миграции.

Ответ 3

От PEP 8:

Принцип переопределения

Имена, видимые пользователю как общедоступные части API, должны соответствовать соглашениям, которые отражают использование, а не реализацию.

Имена пакетов и модулей

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

Единственное, что, кажется, касается вашего вопроса, состоит в том, что подчеркивание в именах пакетов не рекомендуется.

В настоящее время существуют другие PEP, чтобы устранить некоторые несоответствия в упаковке Python в целом (426, 423), но пока эти проблемы не будут решены, я бы пошел с тем, что имеет наибольший смысл в PEP 20. Если super достаточно, чтобы передать импортируемое, то я был бы склонен пойти с этим (хотя, если это так, почему бы и не использовать его для имени пакета PyPi?).

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

Ответ 4

У вас есть правильная идея. соглашение, которое я видел чаще всего, и это хорошо для меня было:

/superduper
    /superduper
        __init__.py
        code.py
    /.git
    setup.py
    README.rst

вы обнаружите, что большинство разработчиков python предпочитают все строчные буквы без специальных символов для имен модулей (setuptools, pexpect, matplotlib и т.д.).
папка проекта верхнего уровня также должна совпадать с именем git repo, так что она не будет изменяться при клонировании git.

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