Если вы разработчик в JavaScript/Node.js Ecosystem, вы использовали NPM Отказ Это крупнейший в мире программный реестр и экосистема вокруг него продвинута и зрелая. Я понял это, когда пытался портировать Пароль - валидатор , пакет NPM с открытым исходным кодом, который я поддерживаю, чтобы Python. Я провел недели, чтобы выяснить вещи, которые были очень интуитивны для меня в мире JavaScript. Этот блог перечисляет некоторые из ключевых различий, которые я нашел между двумя экосистемами для кого-либо еще, кто наступает на тот же путь. К концу этого поста мы должны быть в состоянии установить наш пакет, используя:
pip install
Что такое пакет?
В NPM , любая папка, которая имеет package.json Файл это пакет. В мире Python нам нужен файл под названием setup.py В корневой папке, чтобы сделать наш проект пакет для Pypi , общий репозиторий для пакетов Python. Этот файл используется для объявления метаданных данных, таких как имя, версия, автор и даже зависимости (с уловом). Посмотри на это Образец файла setup.py получить идею.
Обычно фактический код пакета идет внутри каталога с именем пакета, и требуется иметь __ init__.py Файл в нем, чтобы указать, что это модуль. Таким образом, структура каталогов будет выглядеть более или меньше, как:
package-project
├── setup.py
└── my-package
├── __init__.py
└── lib.py
В этой структуре ваш фактический код пакета будет работать __init__.py и/или любой другой файл Python в этом каталоге, как lib.py Отказ
Управление зависимостями
Управление зависимостями – это одна область, в которой я нашел экосистему Python, отсутствующую и изначально. NPM Есть концепции, такие как зависимости и devdependons. и Пакет-замок который делает управление зависимостями проще. Файл манифеста setup.py имеет раздел под названием Установка - требуется который представляет собой список зависимостей, необходимых для запуска проекта. Эти зависимости загружаются при установке пакета, используя пипс . Он не очень широко используется для определения точных зависимостей и зависимостей зависимостей.
Вместо этого используется комбинация виртуальной среды и файла требований.
Виртуальная среда
NPM позволяет устанавливать пакеты по всему миру или локальному в проект. В Пип Все пакеты устанавливаются по всему миру. Чтобы отделить локальные зависимости от пакетов для широких систем, создается виртуальная среда, которая содержит все зависимости локальными для проекта и даже локального распределения Python. Код, работающий в виртуальной среде, не требует какой-либо системной зависимости, поэтому можно гарантировать, что код должен работать во всех системах, где локальная виртуальная среда установлена правильно.
Есть несколько способов настройки виртуальной среды, например Венв и виртуаль . Я нашел бывший, чтобы быть самым простым в использовании.
python3 -m venv
Вышеуказанная команда создает виртуальную среду в каталоге
source/bin/activate
Требования к файлу
Каждая виртуальная среда имеет свое собственное распределение PIP и Python. Так что это чистый сланца, когда вы начинаете. Когда мы устанавливаем зависимости, мы можем сделать их журнал, используя:
pip freeze > requirements.txt
Это будет регистрировать все пакеты и их версии, установленные PIP в файле требования .txt Отказ Имя файла может быть чем угодно Но это конвенция в сообществе Python, чтобы использовать это имя. В Python нет концепции Devdependonds, но для некоторых проектов не редкость есть требования - dev.txt Для регистрации DevDependonds проекта. Вот a Образец требований файл Отказ
Установка зависимостей проекта теперь может быть сделано с:
pip install -r requirements.txt
Документация
Jsdocs является наиболее распространенным способом документирования кода в JavaScript, а список аламста инструментов документации останавливается там. Документация в Python принимается очень серьезно.
Сфинкс
Сфинкс Это генератор документации для Python, который можно использовать различными способами благодаря различным расширениям. Начните с SPHINX, нам нужен Conf.py Файл, который будет иметь конфигурацию для SPHINX. Файл может быть сгенерирован с использованием SPHINX-QuickStart Утилита CLI. Вот a Образец файла conf.py для начала.
Сфинкс и экосистема Python предпочитают использовать реструктурированный текст (Отдых) для документации вместо Markdown, которая распространена в мире JavaScript. M ↓ тоже можно использовать с помощью сфинкса, но это немного работы, а отдых очень похоже на M ↓. Вот образец Readme в покое Отказ
Docstrings.
Сфинкс может просматривать специальные комментарии в Python код и включить их в документацию. Эти комментарии, которые называются Docstrings используются для описания функций, классов и т. Д. И очень похожи на JSDOCS в JavaScript и Javadocs в Java. Вот метод, документированный с DocStrings:
def add(a, b):
''' Performs addition of 2 numbers
Example:
>>> res = add(1, 2)
3
Returns:
int: Result of addition
'''
return a + b
Существует ряд форматов для написания документов, которые могут быть дискуссиями в теме само по себе. Я нашел, что вернусь к Это руководство по realpython И я рекомендую дать ему прочитать для более глубокого понимания Docstrings. Используя комбинацию файлов отдыха и DocStrings, мы можем генерировать документацию с помощью SPHINX в виде типа PDF и HTML. Вот a Образец HTML-документации генерируется с помощью сфинкса.
Есть менее популярные альтернативы SPHINX, которые также могут быть использованы для документирования, наиболее заметной быть ReadTheDocs Отказ
Тесты
Я обнаружил, что написание модульных тестов в Python легче, чем в JavaScript из-за наличия зрелых и встроенных инструментов.
модульный тест
У Python есть встроенный модуль Неизвестный который можно использовать для запуска тестов. Синтаксис очень похож на шутку или мокко. Каждый «тест» – это класс, а каждый метод класса – это тестовый случай. Методы, как Настройка () и Обзор () иметь специальные значения и эквивалентны до и после Методы, видимые в структурах тестирования JavaScript. Вот a Образец тестового файла Отказ Испытания управляются:
python3 -m unittest discover -s
Pteest и Нос2 некоторые из альтернатив Но я нашел Неизвестный адекватный.
Докторы
Ранее в разделе документации мы обсуждали о Docstrings. Раздел «Примеры» в DOCSTRING обеспечивают пользователю понимание того, как использовать функцию. Что отлично, мы также можем запускать пример против автоматического теста на единицу, используя доктра (другой встроенный модуль). Это может сохранить документацию и внедрение в синхронизации.
Издательский
Пакеты могут быть опущены в Pypi после строительства. Ранее сборки были сделаны в формате яиц, однако сейчас он заменяется форматом колеса. Чтобы создать рулевую сборку, нам нужно установить Seturgools. и колесо Отказ
python3 -m pip install --user --upgrade setuptools wheel
Теперь сборка может быть создана бегом:
python3 setup.py sdist bdist_wheel
Это создаст два файла Dist папка:
- Один с
.tar.gzРасширение, которое является исходным архивом. - Другой с
.WHLРасширение, которое является файлом сборки готовым для установки.
Теперь нам нужно загрузить пакет построить в Pypi. Нам нужно шпагат для этого.
python3 -m pip install --user --upgrade twine
Последний шаг, загрузка сборки:
python3 -m twine upload --repository testpypi dist/*
--repository Здесь вы выберете конкретный репозиторий пакета, как пользовательские или частные заменители NPM. Это можно настроить с помощью .pypirc файл.
Дополнительные ресурсы
Два ресурса, которые мне очень помогли в изогнутости, мои проблемы были:
- Официальный Руководство пользователя Python упаковка Отказ Я рекомендую пройти через него один раз.
- Настоящий питон Отказ Я рекомендую нажать на любую ссылку с этого веб-сайта, который подходит в результатах поиска.
Это был интересный опыт для меня, чтобы решить все проблемы, столкнувшись, когда я был в путешествии, чтобы опубликовать мой первый пакет на Pypi. Зрелые структуры тестирования были вдохом свежего воздуха, в то время как управление зависимостями и генерация документации была непростой задачей из-за всех различных инструментов для управления. В конце концов я опубликовал Password_validator И я доволен результатом.
Протяните в комментариях или на моем Twitter Если у вас есть какие-либо проблемы с шагами, которые я упоминал здесь. Счастливое издательство!
Оригинал: “https://dev.to/tbking/pypi-packages-decoded-for-npm-developers-51j4”