Выбор имени для библиотеки Python

Раздел: Окружение разработки -> Пакетный менеджер

Основные принципы именования библиотек Python

Имя библиотеки - это первое, что видят пользователи. Оно влияет на запоминаемость, поиск в PyPI и совместимость с кодом. Чаще всего разработчики следуют рекомендациям PEP 8, но существуют и другие практики.

Базовое решение: имена в нижнем регистре с подчеркиваниями

Главный стандарт - использовать только строчные буквы, цифры и символ подчеркивания. Имя должно быть коротким (1–3 слова), уникальным на PyPI и отражать суть пакета.

# Правильные примеры

# Простое имя
numpy

# Составное с подчеркиванием
sqlalchemy
flask_login

# Для внутренних модулей
my_package.utils

Python naming lib (именование библиотек python)

# Так эти пакеты установлены в системе
pip install flask-login  # на PyPI часто используют дефис, но в импорте он заменяется на подчеркивание

Важно: при публикации на PyPI имя может содержать дефисы, но при импорте они превращаются в подчеркивания. Например, flask-login устанавливается через pip, а в коде пишется import flask_login.

Как избежать конфликтов с популярными библиотеками?

Прежде чем назвать пакет, стоит проверить PyPI на занятость имени. Если имя занято, добавляют суффиксы -py, -python или используют синонимы.

# Пример проверки через pip
pip search my_custom_name  # устаревшая команда, лучше смотреть на pypi.org

Типичная ошибка

Попытка назвать пакет requests для другого протокола. Имя занято, вызовет путаницу. Решение - добавить уточнение: my_requests_fork.

Когда уместно использовать односложные имена?

Короткие имена (например, click, flask) допустимы, если они широко известны и не пересекаются со встроенными модулями. Для нишевых библиотек лучше использовать составные имена.

# Неудачный пример
import str  # конфликт с встроенным типом str

# Удачный
import str_utils

Проблема: односложное имя может быть занято модулем из стандартной библиотеки. Например, string - стандартный модуль. Если опубликовать пакет string, пользователи не смогут одновременно импортировать ваш пакет и стандартный.

Как назвать внутренний модуль в составе большого пакета?

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

# Структура пакета my_lib
my_lib/
    __init__.py
    _internal.py   # приватный модуль
    public_api.py

Цель

Приватные модули (с подчеркиванием в начале) не импортируются по умолчанию при from my_lib import *.

Можно ли использовать CamelCase для публичных библиотек?

PEP 8 рекомендует нижний регистр. CamelCase допустим для имен классов, но не для пакетов. Исключение - библиотеки, которые повторяют названия компаний (например, GoogleCloud).

# Не рекомендуется
import MyLibrary

# Правильно
import my_library

Ошибка: пакет с заглавными буквами может вызвать путаницу на файловых системах с разной чувствительностью к регистру (Linux / Windows).

Заключение

Выбор имени - баланс между читаемостью, уникальностью и практичностью. Основной ориентир - PEP 8 и проверка на PyPI. Альтернативные варианты (CamelCase, дефисы, лидирующие подчеркивания) используются в специальных случаях, но редко для открытых библиотек.

Дополнительные примеры именования с пояснениями

Пример 1. Создание и импорт пакета с правильным именем

Пример

# Файл setup.py для пакета my_calc
from setuptools import setup, find_packages

setup(
    name='my-calc',          # дефис в PyPI
    version='1.0.0',
    packages=find_packages(),
    python_requires='>=3.6',
)

# Установка и импорт
$ pip install my-calc
>>> import my_calc   # подчеркивание в коде

Многие новички пишут import my-calc, что вызывает SyntaxError. Пояснение: pip автоматически заменяет дефис на подчеркивание при импорте.

Пример 2. Использование префиксов для приватных модулей

Пример

# Модуль _secret.py внутри пакета
# _secret.py
def _internal_helper():
    return 'секретные данные'

# __init__.py
from ._secret import _internal_helper  # явный импорт возможен
__all__ = []  # не экспортируется

>>> from my_package import *
# _internal_helper не импортируется
>>> from my_package._secret import _internal_helper
# явный импорт работает, но считается нарушением инкапсуляции

Пример 3. Имена с версией или суффиксом для форков

Пример

# Если оригинал занят
# Оригинальный пакет: requests
# Форк: requests-fork

# В setup.py
name='requests-fork'

# Установка
pip install requests-fork

# Импорт
import requests_fork as req

Проблема: при попытке установить и оригинал, и форк возникнет конфликт. Решение - использовать разные корневые пакеты: requests_official и requests_custom.

Пример 4. Тестирование конфликтов с встроенными модулями

Пример

# Попытка импорта модуля с именем, совпадающим со встроенным
import sys
sys.path.insert(0, '/path/to/my_package')

# Если в my_package есть file.py, он перекроет встроенный модуль file
# Встроенный модуль file не существует, но допустим, есть модуль 'datetime'
import datetime  # ваш или встроенный?

# Проверка: если сначала идет ваш путь, то загрузится ваш модуль.
# Чтобы избежать, не называйте пакеты как стандартные модули (os, sys, datetime, json и т.д.)

Пример 5. Имена с подчеркиванием в конце для избежания зарезервированных слов

Пример

# Нельзя использовать 'class' как имя пакета
# Но можно 'class_' - по PEP 8 для переменных
# Однако для пакетов лучше выбрать другое слово: 'classes' или 'classifier'

Такое имя (с подчеркиванием) для пакета выглядит неестественно. Лучше переименовать.

Пример 6. Множественные вариации одного пакета (для разных версий Python)

Пример

# Например, библиотека может иметь Python 2 и Python 3 версии
# Имена: mylib_py2, mylib_py3
# Но лучше использовать одну кодовую базу с conditional imports.

# Устаревший подход. Сейчас рекомендуется использовать совместимый код без разделения имён.

Именование библиотек Python - comments

Python naming lib (python)