python-package-development

«Подобно тому, как Хэдли Уикхэм принёс Grammar of Graphics в R в виде ggplot2, этот скилл переносит философию разработки R-пакетов в Python.»

Что это такое?

python-package-development — плагин для Claude Code, который учит Claude правильно собирать Python-пакеты, используя проверенную мудрость экосистемы R.

Для Python-разработчиков, которые хотят, чтобы их пакеты были такими же отполированными, как tidyverse R-пакеты — независимо от того, создаёте ли вы первую библиотеку или поддерживаете production-пакет.

В Python есть отличные пакеты. Но единой философии их создания никогда не было. В мире R она есть: книга Хэдли Уикхэма R Packages (совместно с Дженни Брайан), подкреплённая инструментами devtools, usethis, roxygen2, cli и lifecycle.

Этот плагин переводит ту философию на Python с помощью современных инструментов: uv, rich, pytest и mkdocs-material.

Установка

Через маркетплейс плагинов (рекомендуется)

/plugin marketplace add Naareman/python-package-development
/plugin install python-package-development@python-package-development

Ручная установка (персональная область)

bash

git clone https://github.com/Naareman/python-package-development.git
cp -r python-package-development/skills/python-package-development \
  ~/.claude/skills/python-package-development

Проверка установки

В Claude Code введите /python-package-development — скилл должен появиться в списке.

Примеры

Создать новый пакет с нуля

Вы:  /python-package-development scaffold my-analytics-lib

Claude создаёт полную структуру пакета в соответствии со всеми соглашениями:

my-analytics-lib/
├── pyproject.toml          # uv + hatchling, PEP 735 dependency-groups
├── mkdocs.yml              # mkdocs-material с mkdocstrings
├── src/
│   └── my_analytics_lib/
│       ├── __init__.py     # curated __all__, importlib.metadata version
│       ├── py.typed        # маркер типов PEP 561
│       ├── errors.py       # базовое исключение + типизированные ошибки
│       ├── _messages.py    # rich console (info, success, warn, abort)
│       └── core.py         # функции verb_noun() с Google docstrings
├── tests/
│   ├── conftest.py         # общие фикстуры
│   └── test_core.py        # happy path + обработка ошибок
└── docs/
    ├── index.md
    └── api.md

Проверить дизайн API

Вы:  /python-package-development api

Claude читает ваш код и проверяет:

Названы ли функции по схеме verb_noun()? Согласованы ли семейства?
Находятся ли ошибки в errors.py с правильной иерархией?
Используется ли _messages.py вместо голого print()?
Есть ли у каждой публичной функции Google-style docstring?

Аудит на типичные ошибки

Вы:  /python-package-development check

Claude сканирует проект на 30+ известных антипаттернов:

Указан ли верхний предел в requires-python?
Попали ли dev-зависимости в [project] dependencies?
Используется ли --cov=src вместо --cov=my_package?
Отсутствует ли py.typed? Существует ли tests/__init__.py?
Используется ли устаревший формат license = { text = "MIT" }?

Настроить pre-commit хуки

Вы:  /python-package-development pre-commit

Claude добавляет .pre-commit-config.yaml с ruff (lint + format), mypy и стандартными хуками — без black, isort и flake8.

Правильно устаревить функцию

Вы:  Мне нужно переименовать parse_file() в read_csv()

Скилл активируется автоматически и проводит через процедуру устаревания:

Оставить parse_file(), добавить DeprecationWarning со ссылкой на read_csv()
Указать срок удаления в docstring и CHANGELOG
Удалить в обещанной версии

Подготовить релиз на PyPI

Вы:  /python-package-development release

Claude проводит через ритуал релиза:

Все тесты проходят? Lint чист? Типы проверены?
CHANGELOG обновлён? Версия поднята?
Git-тег создан? Тег запушен?
CI публикует на PyPI автоматически через trusted publishing

Просто спросите своими словами

Скилл также активируется, когда вы описываете задачу:

Вы:  Хочу сделать Python-библиотеку для парсинга конфигурационных файлов
Вы:  Помоги структурировать код как пакет
Вы:  Как мне называть эти функции?
Вы:  Как опубликовать на PyPI?

Философия (чему нас научил R)

1. Коммуникация с пользователем — это первоклассная задача

Пакет cli в R сделал красивые структурированные сообщения простыми. Этот скилл привносит то же самое в Python через rich и иерархии исключений.

2. Имена функций образуют грамматику

Tidyverse-пакеты последовательно используют verb_noun(). Пользователи могут угадывать имена функций, потому что грамматика предсказуема.

3. Жизненный цикл заслуживает церемонии

Пакет lifecycle в R дал устареванию формальный процесс. Пользователи никогда не бывают застигнуты врасплох.

4. Документация живёт рядом с кодом

roxygen2 сделал невозможным забыть документацию. Этот скилл обеспечивает соблюдение Google-style docstrings + mkdocstrings.

5. Нужно видеть всю картину целиком

Прежде чем погружаться в детали, стоит увидеть, как всё работает от начала до конца.

Что охватывает этот скилл

Этап	Аналог в R	Python
Создание структуры	`usethis::create_package()`	`uv init` + src layout
Управление зависимостями	`DESCRIPTION` + `devtools`	`pyproject.toml` + `uv`
Сообщения пользователю	пакет `cli`	`rich` Console
Структурированные ошибки	`rlang::abort()`	Иерархия пользовательских исключений
Именование API	tidyverse-соглашения	`verb_noun`, семейства, префиксы
Тестирование	`testthat`	`pytest` + фикстуры
Документация	`roxygen2` + `pkgdown`	Google docstrings + `mkdocs-material`
Жизненный цикл	пакет `lifecycle`	`warnings` + соглашения об устаревании
Релиз	`devtools::release()`	GitHub Actions + PyPI
Pre-commit	`lintr` + `styler`	ruff + mypy + pre-commit
CLI	`Rscript`	`click` / `argparse` + entry points
Монорепозиторий	—	uv workspaces + namespace packages
Автоматический релиз	—	`bump-my-version` + `git-cliff`

Структура плагина

python-package-development/
├── skills/
│   └── python-package-development/
│       ├── skill.md              # основной файл скилла
│       ├── docs/                 # 11 справочных документов
│       │   ├── api-design.md
│       │   ├── changelog.md
│       │   ├── cli.md
│       │   ├── dependencies.md
│       │   ├── documentation.md
│       │   ├── errors.md
│       │   ├── lifecycle.md
│       │   ├── messages.md
│       │   ├── monorepo.md
│       │   ├── release.md
│       │   └── testing.md
│       └── example/              # полный пример пакета
│           └── mylib/
└── README.md

Лицензия

MIT

Разработка Python-пакетов

Установка

README

python-package-development

Что это такое?

Установка

Через маркетплейс плагинов (рекомендуется)

Ручная установка (персональная область)

Проверка установки

Примеры

Создать новый пакет с нуля

Проверить дизайн API

Аудит на типичные ошибки

Настроить pre-commit хуки

Правильно устаревить функцию

Подготовить релиз на PyPI

Просто спросите своими словами

Философия (чему нас научил R)

1. Коммуникация с пользователем — это первоклассная задача

2. Имена функций образуют грамматику

3. Жизненный цикл заслуживает церемонии

4. Документация живёт рядом с кодом

5. Нужно видеть всю картину целиком

Что охватывает этот скилл

Структура плагина

Лицензия

Похожие скиллы

pg-aiguide

convexskills

Skills и Agents для Java

Elixir Phoenix плагин