Существуют ли правила для именования одномодульных пакетов 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

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

11
package pypi python python-module

4 ответов

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

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

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

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

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

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

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

  • Это делает одинаковое имя.

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

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

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

9

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

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

  • на проект BeautifulSoup использует beautifulsoup4 для имени проекта на PyPI, который устанавливает пакет bs4.

  • на dateutil пакет Python доступен на PyPI как python-dateutil. Префиксация имен проектов PyPI с python- достаточно распространен, я насчитал 1512 таких пакетов на PyPI сегодня.

  • на Viivakoodi проект является вилкой pyBarcode. Их viivakoodi проект PyPI установка barcode пакета site-packages. Еще один такой проект fork -подушка, который является вилкой библиотеки изображений Python. Он доступен на PyPI под именем но пакет устанавливает .

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

5

С PEP 8:

Основополагающим Принципом

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

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

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

единственное, что здесь, похоже, решает ваш вопрос, - это то, что подчеркивания в именах пакетов не поощряются.

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

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

3

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

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

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

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

2