چگونه اولین کتابخانه پایتون خود را بسازیم و در PyPI منتشر کنیم؟(تجربه ساخت کتابخانه فارسی)

حسن باقری(hasan bagheri) — Mon, 22 Jun 2026 12:42:08 +0000

چگونه اولین کتابخانه پایتون خود را بسازیم و در PyPI منتشر کنیم؟ (تجربه ساخت کتابخانه‌ای برای متن فارسی)

همه ما در پروژه‌های پایتون با نیازهای تکراری مواجه می‌شویم: نرمال‌سازی متن فارسی، تبدیل اعداد، اعتبارسنجی شماره موبایل و ... در این مقاله قدم‌به‌قدم نشان می‌دهم که چطور این قابلیت‌ها را در یک کتابخانه جمع‌آوری کرده و آن را در PyPI منتشر کردم.

چرا این مقاله را بخوانیم؟

یادگیری عملی: با ساختار استاندارد کتابخانه‌های پایتون آشنا می‌شوید.
انتشار واقعی: از صفر تا انتشار در PyPI را تجربه می‌کنید.
کمک به جامعه: کتابخانه‌تان به کار دیگر توسعه‌دهندگان می‌آید.

پیش‌نیازها

آشنایی مقدماتی با پایتون
نصب Python و pip روی سیستم
یک حساب کاربری در GitHub و PyPI ## ۱. ساختار پروژه

ابتدا پوشه‌ای با این ساختار ایجاد کنید:
persiantools/
├── src/
│ └── pypersian/
│ ├── init.py
│ └── text_utils.py
├── tests/
│ └── init.py
├── README.md
├── LICENSE
└── pyproject.toml

پوشه src حاوی کدهای اصلی کتابخانه است.
فایل pyproject.toml استاندارد جدید برای تعریف کتابخانه‌های پایتون است. ## ۲. نوشتن کدهای کتابخانه

فایل `src/pypersian/text_utils.py`

این فایل شامل توابع اصلی کتابخانه است:

def normalize_text(text: str) -> str:
    """نرمال‌سازی متن فارسی"""
    if not text:
        return text
    text = text.replace('ي', 'ی')
    text = text.replace('ك', 'ک')
    text = ' '.join(text.split())
    return text

def persian_to_english_numbers(text: str) -> str:
    """تبدیل اعداد فارسی به انگلیسی"""
    if not text:
        return text
    persian_numbers = {
        '۰': '0', '۱': '1', '۲': '2', '۳': '3', '۴': '4',
        '۵': '5', '۶': '6', '۷': '7', '۸': '8', '۹': '9'
    }
    for persian, english in persian_numbers.items():
        text = text.replace(persian, english)
    return text

def validate_iran_mobile(number: str) -> bool:
    """اعتبارسنجی شماره موبایل ایران"""
    import re
    number = number.replace(" ", "").replace("-", "").replace("_", "")
    pattern = r"^(0|98)?9\d{9}$"
    return bool(re.match(pattern, number))

فایل src/pypersian/init.py
این فایل کتابخانه را قابل import می‌کند:
from .text_utils import normalize_text, persian_to_english_numbers, validate_iran_mobile

version = "0.1.1"
all = ["normalize_text", "persian_to_english_numbers", "validate_iran_mobile"]

📄 بخش پنجم: فایل‌های تنظیمات

## ۳. فایل‌های تنظیمات و مستندات

### فایل `pyproject.toml`

این فایل استاندارد برای تعریف کتابخانه است:

toml
[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "pypersian"
version = "0.1.1"
description = "ابزارهای کاربردی برای پردازش متن و داده‌های فارسی"
readme = "README.md"
authors = [
{name = "Hasan Bagheri", email = "hasan111bagher0@gmail.com"}
]
license = {text = "MIT"}
classifiers = [
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
"Natural Language :: Persian",
"Topic :: Text Processing",
]
requires-python = ">=3.7"
dependencies = []
[project.urls]
Homepage = "https://github.com/0hasanbagheri0/pypersian"
Repository = "https://github.com/0hasanbagheri0/pypersian"
Issues = "https://github.com/0hasanbagheri0/pypersian/issues"
[tool.setuptools.packages.find]
where = ["src"]

##فایل README.md

plaintext

PyPersian

ابزارهای کاربردی برای پردازش متن و داده‌های فارسی در پایتون.

ویژگی‌ها

نرمال‌سازی متن فارسی (تبدیل ي و ك عربی به ی و ک فارسی)
تبدیل اعداد فارسی به انگلیسی (مثلاً ۱۲۳ → 123)
اعتبارسنجی شماره موبایل ایران

## نصب

bash
pip install pypersian


مثال استفاده

python
python
from pypersian import normalize_text, persian_to_english_numbers, validate_iran_mobile

print(normalize_text("يك متن فارسي")) # خروجی: یک متن فارسی
print(persian_to_english_numbers("۱۲۳۴۵")) # خروجی: 12345
print(validate_iran_mobile("09123456789")) # خروجی: True

#مجوز
MIT
متن رو باید بسازید
---
---

📄 بخش ششم: تست و انتشار
---

## ۴. تست محلی کتابخانه

قبل از انتشار، کتابخانه را به‌صورت محلی تست کنید:

bash

در پوشه پروژه

pip install -e .
python -c "from pypersian import normalize_text; print(normalize_text('يك تست'))"

خروجی باید یک تست باشد.
---

##۵. انتشار در PyPI
---

#گام اول: نصب ابزارهای مورد نیاز

bash
pip install --upgrade build twine

#گام دوم: ساخت فایل‌های قابل انتشار

bash
python -m build

این دستور پوشه dist را با دو فایل .tar.gz و .whl می‌سازد.
---
##گام سوم: دریافت توکن PyPI
به pypi.org بروید.

در Account settings > API tokens یک توکن جدید با Scope "Entire account" بسازید.

توکن را کپی کنید.
---

##گام چهارم: انتشار