اگر کدی نوشته‌اید که بارها کپی می‌کنید — یک تابع کاربردی، یک کلاینت API یا یک ابزار کوچک — وقتش رسیده آن را به یک پکیج پایتون استاندارد تبدیل کنید و روی PyPI منتشر کنید تا با یک دستور pip install همه جا قابل نصب باشد. این راهنما دقیقا همین مسیر را قدم‌به‌قدم و با ساختار مدرن pyproject.toml به شما نشان می‌دهد؛ بدون نیاز به setup.py قدیمی و بدون سردرگمی در نسخه‌گذاری.

ساخت و انتشار پکیج پایتون در PyPI چقدر زمان می‌برد و چه می‌خواهید؟

با پایتون ۳.۹ به بالا، یک فایل pyproject.toml استاندارد، ابزار build و twine و یک حساب رایگان PyPI می‌توانید در کمتر از ۳۰ دقیقه اولین پکیج خود را بیلد کنید، روی TestPyPI آزمایش کنید و سپس روی PyPI اصلی منتشر کنید. در ادامه تمام مراحل، از ساختار پوشه تا انتشار نسخه جدید را با کد آماده می‌بینید.

فهرست مطالب

پیش‌نیازها و ابزارهای لازم قبل از شروع
ساختار استاندارد یک پکیج پایتون مدرن
نوشتن pyproject.toml حرفه‌ای
اولین بیلد و تست محلی با pip
انتشار آزمایشی روی TestPyPI
انتشار نهایی روی PyPI و نسخه‌گذاری معنایی
مقایسه ابزارهای بیلد و انتشار
اشتباهات رایج هنگام انتشار پکیج پایتون
سوالات متداول
جمع‌بندی

پیش‌نیازها و ابزارهای لازم قبل از شروع

قبل از کدنویسی، محیط را تمیز و به‌روز کنید. این کار از ۸۰٪ خطاهای رایج هنگام بیلد جلوگیری می‌کند.

پایتون و pip به‌روز

از پایتون ۳.۹ به بالا استفاده کنید و pip و build را به آخرین نسخه ارتقا دهید. ساختار پیشنهادی روی ویندوز، مک و لینوکس یکسان است.

python --version
python -m pip install --upgrade pip build twine

ابزار build بسته‌های sdist و wheel را می‌سازد و twine آن‌ها را امن به PyPI آپلود می‌کند. اگر مدیریت محیط مجازی برایتان چالش است، بد نیست نگاهی به آموزش اجرای لوکال مدل‌ها با Ollama بیندازید تا مدیریت محیط‌های ایزوله را بهتر درک کنید — هرچند موضوع آن متفاوت است، الگوی ایزوله‌سازی مشابه است.

حساب PyPI و TestPyPI و توکن API

در pypi.org و test.pypi.org ثبت‌نام کنید و از بخش Account settings یک API Token بسازید. توکن را در فایل ~/.pypirc یا متغیر محیطی TWINE_USERNAME=__token__ و TWINE_PASSWORD=pypi-xxx نگه دارید. هرگز توکن را داخل کد کامیت نکنید.

# ~/.pypirc نمونه امن
[distutils]
index-servers = pypi testpypi

[pypi]
username = __token__
password = pypi-xxxxxxxx

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-YYYYYYYY

ساختار استاندارد یک پکیج پایتون مدرن

دیگر نیازی به setup.py نیست. ساختار پیشنهادی امروز src layout است که از ایمپورت اشتباه هنگام تست جلوگیری می‌کند.

my-tool/
├── src/
│   └── my_tool/
│       ├── __init__.py
│       └── core.py
├── tests/
│   └── test_core.py
├── pyproject.toml
├── README.md
└── LICENSE

فایل __init__.py نسخه را نگه می‌دارد: __version__ = "0.1.0". فایل README.md با فرمت Markdown توضیحات PyPI شما خواهد بود. لایسنس MIT را فراموش نکنید. اگر قصد دارید بعد از انتشار یک دمو تعاملی هم بسازید، می‌توانید با آموزش Streamlit برای اپ تعاملی یک صفحه معرفی برای پکیج خود بسازید.

چرا src layout بهتر است؟

در src layout، کد سورس فقط وقتی قابل ایمپورت است که نصب شده باشد. این یعنی تست‌ها دقیقا همان چیزی را می‌بینند که کاربر نهایی می‌بیند، نه پوشه محلی را. در flat layout تست‌ها ممکن است به اشتباه ماژول لوکال را لود کنند و باگ نصب پنهان بماند.

نوشتن pyproject.toml حرفه‌ای

قلب پکیج همین فایل است. مطابق PEP 621 تمام متادیتا اینجا جمع می‌شود.

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-tool"
version = "0.1.0"
description = "ابزار کوچک برای تبدیل متن به اسلاگ فارسی"
readme = "README.md"
requires-python = ">=3.9"
license = {text = "MIT"}
authors = [{name = "Your Name", email = "you@example.com"}]
keywords = ["python", "pypi", "package"]
dependencies = []
classifiers = [
  "Programming Language :: Python :: 3",
  "License :: OSI Approved :: MIT License",
]

[project.urls]
Homepage = "https://github.com/you/my-tool"
Issues = "https://github.com/you/my-tool/issues"

[project.scripts]
my-tool = "my_tool.core:main"

نکات کلیدی: نام پکیج در PyPI باید یکتا باشد — قبل از انتخاب نهایی در pypi.org جستجو کنید. فیلد readme باید به فایل واقعی اشاره کند وگرنه صفحه PyPI خالی می‌ماند. برای وابستگی‌ها، نسخه‌های بازه‌ای مثل requests>=2.28,<3 ایمن‌تر از پین دقیق هستند.

اولین بیلد و تست محلی با pip

قبل از هر آپلود، پکیج را محلی بیلد و نصب کنید.

# در ریشه پروژه
python -m build
# خروجی: dist/my_tool-0.1.0.tar.gz و dist/my_tool-0.1.0-py3-none-any.whl

# تست نصب در محیط مجازی تمیز
python -m venv .venv
# ویندوز: .venv\Scripts\activate
source .venv/bin/activate
pip install dist/my_tool-0.1.0-py3-none-any.whl
my-tool --help
python -c "import my_tool; print(my_tool.__version__)"

اگر دستور my-tool کار نکرد، بخش [project.scripts] را چک کنید. اگر ایمپورت شکست خورد، نام پوشه داخل src باید دقیقا با import یکی باشد (خط تیره - در نام PyPI به آندرلاین _ در ایمپورت تبدیل می‌شود).

تست خودکار قبل از انتشار

pip install pytest
pytest -q

یک تست ساده کافی است تا مطمئن شوید بیلد خراب نیست.

انتشار آزمایشی روی TestPyPI

TestPyPI یک PyPI قلابی برای تمرین است. همیشه اول اینجا منتشر کنید.

twine upload --repository testpypi dist/*
# نصب آزمایشی از TestPyPI
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple my-tool

چون TestPyPI وابستگی‌ها را ندارد، فلگ --extra-index-url لازم است تا وابستگی‌ها از PyPI اصلی بیایند. اگر نسخه 0.1.0 را قبلا آپلود کرده‌اید، نمی‌توانید دوباره همان نسخه را بازنویسی کنید — باید به 0.1.1 بروید.

انتشار نهایی روی PyPI و نسخه‌گذاری معنایی

وقتی تست TestPyPI موفق بود، به سراغ PyPI اصلی بروید.

twine upload dist/*
pip install my-tool

بعد از انتشار، نسخه جدید را با Semantic Versioning مدیریت کنید: MAJOR.MINOR.PATCH — افزایش PATCH برای باگ‌فیکس، MINOR برای قابلیت جدید سازگار، MAJOR برای تغییر شکننده. این قانون را در pyproject.toml و __init__.py همزمان اعمال کنید.

# انتشار نسخه جدید
# 1. تغییر version به 0.2.0 در pyproject.toml
# 2. بیلد تمیز
rm -rf dist/ build/
python -m build
twine upload dist/*
git tag v0.2.0 && git push --tags

از Trusted Publisher با OIDC در GitHub Actions هم می‌توانید بدون توکن دستی منتشر کنید — در PyPI بخش Publishing را به ریپازیتوری گیت‌هاب وصل کنید.

مقایسه ابزارهای بیلد و انتشار

انتخاب ابزار به سبک کاری شما بستگی دارد.

ابزار	مزیت اصلی	محدودیت	مناسب برای
hatchling + build + twine	استاندارد PEP 621، سبک و سریع	مدیریت دستی نسخه	پکیج‌های کوچک و متوسط
Poetry	مدیریت وابستگی و انتشار یکجا	ساختار اختصاصی poetry.toml	پروژه‌های با وابستگی زیاد
PDM	پشتیبانی کامل PEP 582	جامعه کوچک‌تر	تیم‌های علاقه‌مند به استاندارد نو
setuptools (setup.py)	سازگاری قدیمی	منسوخ و پیچیده	پروژه‌های لگاسی

برای شروع، hatchling ساده‌ترین و آینده‌دارترین گزینه است و نیازی به یادگیری ابزار جدید ندارد.

اشتباهات رایج هنگام انتشار پکیج پایتون

این پنج خطا را بارها دیده‌ایم — با رعایت آن‌ها انتشار شما بی‌دردسر می‌شود:

نام تکراری: بدون جستجو در PyPI نام انتخاب می‌کنید و آپلود با خطای 403 رد می‌شود. راه حل: قبل از بیلد، نام را در pypi.org و test.pypi.org چک کنید و یک پیشوند خاص اضافه کنید.
فراموشی README و LICENSE: صفحه PyPI خالی یا بدون لایسنس می‌ماند و نصب‌کنندگان اعتماد نمی‌کنند. حتما readme = "README.md" و فایل LICENSE را اضافه کنید.
نسخه تکراری: تلاش برای آپلود دوباره نسخه قبلی. PyPI نسخه را immutable می‌داند. هر آپلود باید نسخه جدید باشد، حتی برای تست.
آپلود از محیط آلوده: پوشه dist قدیمی را پاک نمی‌کنید و فایل‌های قدیمی دوباره آپلود می‌شوند. هر بار rm -rf dist build بزنید.
لو رفتن توکن: توکن را در کد یا اسکرین‌شات منتشر می‌کنید. از متغیر محیطی یا OIDC استفاده کنید و توکن لو رفته را فورا در PyPI باطل کنید.

سوالات متداول

آیا برای انتشار پکیج حتما باید از setup.py استفاده کنم؟

خیر. از سال ۲۰۲۳ استاندارد PEP 621 با pyproject.toml جایگزین setup.py شده است. فقط اگر پروژه بسیار قدیمی دارید و افزونه خاص setuptools نیاز دارید سراغ setup.py بروید، وگرنه hatchling یا Poetry مدرن‌تر است.

چرا نصب از TestPyPI وابستگی‌ها را پیدا نمی‌کند؟

TestPyPI فقط پکیج شما را دارد نه وابستگی‌هایش. هنگام نصب تست حتما --extra-index-url https://pypi.org/simple را اضافه کنید تا pip وابستگی‌ها را از PyPI اصلی بیاورد.

چطور بدون توکن دستی با GitHub Actions منتشر کنم؟

در PyPI به بخش Your projects > Publishing > Add a new pending publisher بروید و ریپازیتوری گیت‌هاب را به عنوان Trusted Publisher ثبت کنید. سپس در ورک‌فلو از pypa/gh-action-pypi-publish@release/v1 استفاده کنید؛ نیازی به ذخیره توکن نیست.

نام پکیج من قبلا گرفته شده، چه کنم؟

یک نام توصیفی‌تر انتخاب کنید، مثلا my-tool-fa یا my-tool-lite. نام PyPI با ایمپورت فرق دارد؛ می‌توانید نام PyPI را my-tool-fa بگذارید ولی ایمپورت همچنان import my_tool بماند.

هر بار برای نسخه جدید چه مراحلی را تکرار کنم؟

نسخه را در pyproject.toml و __init__.py بالا ببرید، rm -rf dist build بزنید، python -m build و twine upload را اجرا کنید و در گیت تگ بزنید. این چرخه کمتر از ۲ دقیقه طول می‌کشد.

آیا می‌توانم پکیج را بعد از انتشار حذف کنم؟

حذف کامل توصیه نمی‌شود و فقط برای نسخه‌های بسیار جدید و معیوب با درخواست دستی ممکن است. بهتر است نسخه جدید با فیکس منتشر کنید و در توضیحات نسخه قبلی هشدار deprecation بگذارید.

جمع‌بندی

ساخت و انتشار پکیج پایتون دیگر کار ترسناکی نیست اگر مسیر استاندارد را بروید:

ساختار src/my_tool بسازید و pyproject.toml را با hatchling پر کنید.
با python -m build بیلد کنید و در محیط مجازی تمیز با pip install تست کنید.
اول روی TestPyPI با twine upload --repository testpypi آزمایش کنید.
روی PyPI اصلی منتشر کنید و نسخه‌گذاری معنایی را رعایت کنید.
برای انتشارهای بعدی، dist را پاک کنید، نسخه را بالا ببرید و با تگ گیت منتشر کنید.
برای اتوماسیون، Trusted Publisher گیت‌هاب را فعال کنید تا بدون توکن دستی منتشر شود.

همین امروز یک ابزار کوچک خود را بسته‌بندی کنید — اولین pip install موفق از PyPI حس فوق‌العاده‌ای دارد و مسیر شما را برای پروژه‌های بزرگ‌تر هموار می‌کند.

آموزش ساخت و انتشار پکیج پایتون در PyPI از صفر تا نصب