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

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

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

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

 import super_duper 

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

4 Solutions collect form web for “Существуют ли правила для именования одномодульных пакетов Python?”

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

От PEP 8 :

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

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

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

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

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

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

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

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

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

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

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

  • Перезагрузка модуля Python для каждого процесса в модуле многопроцессорности
  • PyInstaller не может найти libpython2.7.so при создании двоичного кода?
  • Невозможно импортировать модуль python, который определенно установлен (механизировать)
  • Импорт всего (*) динамически из модуля
  • Проверка установленных зависимостей модулей Python
  • Перезагрузите модуль в Python 3.4
  • Модули импорта Python, структуры папок
  • Программно определить расположение файлов данных distutils в Python
  • pip: непоследовательные проблемы с разрешениями
  • Как использовать importlib для импорта модулей из произвольных источников?
  • Модуль загрузки Python ImportError в подпапке
  • Python - лучший язык программирования в мире.