# نخستین بستهٔ پایتون خود را در ۵ دقیقه منتشر کنید

> یک بستهٔ واقعی پایتون از یک پوشهٔ خالی تا pip install، گام به گام، با tinyhash (منتشرشده روی زرین) به‌عنوان نمونه. چیدمان پروژه، نامی آزاد، ساختن، توکن انتشار، بارگذاری، نصب، گذاشتن کد روی زرین و نسخهٔ بعدی.

Source: https://zaryn.xyz/docs/fa/publish-python-package

همهٔ آنچه در ادامه می‌آید واقعاً انجام شده: [tinyhash](/arvand/tinyhash) ابزار کوچکی به زبان پایتون است که به همین روش روی زرین منتشر شده. اول امتحانش کنید:

```bash
pip install --index-url https://api.zaryn.xyz/v1/packages/pypi/all/simple/ tinyhash
tinyhash .
```

```diagram
type: flow
title: از یک پوشه کد تا pip install
---
نوشتن | کد شما و یک pyproject.toml | | 📝
~ python -m build
ساختن | یک wheel و یک بایگانی منبع | | 🛠
~ با توکن انتشار: twine upload
انتشار | روی زرین، با نامی که مال کس دیگری نیست | accent | ⇡
~ pip install
هر کسی نصبش می‌کند | از همان نشانی‌ای که همهٔ pypi.org را می‌دهد | good | ✓
```

## ۱. چیدمان پروژه

```diagram
type: cards
---
📄 | pyproject.toml | نام، نسخه، توضیح و فرمان بسته | accent
📁 | src/tinyhash/ | کد: `__init__.py` و ماژول‌ها |
🧪 | tests/ | تا پیش از نصب دیگران بدانید کار می‌کند |
📘 | README.md | در صفحهٔ بسته و صفحهٔ اول مخزن نشان داده می‌شود | good
⚖ | LICENSE | می‌گوید دیگران با آن چه می‌توانند بکنند (MIT کوتاه و رایج است) |
```

کل `pyproject.toml` بستهٔ tinyhash:

```toml
[build-system]
requires = ["setuptools>=77"]
build-backend = "setuptools.build_meta"

[project]
name = "tinyhash"
version = "0.1.0"
description = "A short fingerprint for any file or folder."
readme = "README.md"
license = "MIT"
requires-python = ">=3.9"

[project.urls]
Source = "https://zaryn.xyz/arvand/tinyhash"

[project.scripts]
tinyhash = "tinyhash.cli:main"

[tool.setuptools.packages.find]
where = ["src"]
```

بخش `[project.scripts]` است که `pip install tinyhash` را به فرمانی به نام `tinyhash` تبدیل می‌کند. برای یک کتابخانه آن را حذف کنید.

## ۲. نامی آزاد انتخاب کنید

نام **تازه** روی زرین نباید روی pypi.org وجود داشته باشد: این کار یک فهرست را برای همه امن نگه می‌دارد ([چرا](/docs/fa/packages-pypi#انتخاب-نام)). پیش از ساختن بررسی کنید:

```bash
curl -s -o /dev/null -w "%{http_code}\n" https://pypi.org/pypi/tinyhash/json
```

`404` یعنی آزاد است. اگر گرفته شده، پیشوند خودتان را بیفزایید (`acme-tinyhash`).

## ۳. بسازیدش

```bash
python -m pip install build twine
python -m build
twine check dist/*
```

حالا در `dist/` دو فایل `tinyhash-0.1.0-py3-none-any.whl` و `tinyhash-0.1.0.tar.gz` هست. `twine check` مطمئن می‌شود README درست نشان داده می‌شود.

## ۴. توکن انتشار بگیرید

در [بسته‌ها](/packages)، **Create a publish token** را بزنید. همان لحظه کپی‌اش کنید: فقط یک بار نشان داده می‌شود. فقط می‌تواند بسته منتشر کند، پس حتی اگر لو برود کسی با آن به مخزن‌ها یا حسابتان دست نمی‌زند.

## ۵. بارگذاری‌اش کنید

```bash
twine upload --repository-url https://api.zaryn.xyz/v1/packages/pypi/ \
  -u __token__ -p YOUR_TOKEN dist/*
```

`__token__` را همان‌طور بنویسید. حالا بسته صفحهٔ خودش را دارد و هر کسی می‌تواند نصبش کند:

```bash
pip install --index-url https://api.zaryn.xyz/v1/packages/pypi/all/simple/ tinyhash
```

وابستگی‌هایش از pypi.org هم از همین نشانی می‌آیند.

## ۶. کد را هم روی زرین بگذارید

بسته حاصل کار است؛ مخزن جایی است که دیگران کد را می‌خوانند، تاریخچه را می‌بینند و تغییر می‌فرستند. از پوشهٔ پروژه:

```bash
zev new
zev add .
zev commit -m "tinyhash 0.1.0"
zev push
```

`zev new` مخزن را می‌سازد و وصلش می‌کند؛ README صفحهٔ اول آن می‌شود. یک توضیح یک‌خطی هم در **Settings** مخزن بیفزایید.

## ۷. نسخهٔ بعدی

```diagram
type: cards
---
🔢 | نسخه را بالا ببرید | `0.1.0` ← `0.1.1` در pyproject.toml: نسخه‌ای که یک بار بارگذاری شد جایگزین نمی‌شود | accent
🛠 | دوباره بسازید | اول `dist/` قدیمی را پاک کنید، سپس `python -m build` |
⇡ | بارگذاری | همان فرمان twine؛ pip تازه‌ترین نسخه را برمی‌دارد | good
```

بیشتر: بسته‌های خصوصی، uv و Poetry، و توضیح همهٔ خطاها در [بسته‌های پایتون](/docs/fa/packages-pypi).