چطور در ۱۰ روز یک ابزار خط فرمان با ۶۲ دستور ساختم و روPYPI منتشر کردم....

مقدمه: یک درد قدیمی

یادم میاد چند ماه پیش، وسط یک پروژهٔ وب بودم و باید یه تاریخ میلادی رو به شمسی تبدیل می‌کردم. مثل هر توسعه‌دهندهٔ دیگه‌ای، سریع رفتم سراغ jdatetime. کار کرد، ولی حس کردم چیزی کمه.

چرا باید برای هر کار کوچیک، یه اسکریپت پایتون بنویسم؟

• تبدیل تاریخ؟ یه اسکریپت

• اصلاح نیم‌فاصله در متن؟ یه اسکریپت

• تبدیل عدد به حروف فارسی؟ یه اسکریپت

• تولید رمز قوی؟ یه اسکریپت

اینجا بود که به خودم گفتم: چرا همهٔ این‌ها توی یک ابزار CLI نباشه؟

این شروع ماجرای persian-devkit بود — یک جعبه‌ابزار خط فرمان که امروز به نسخهٔ ۲.۰.۰ با ۶۲ دستور رسیده.

چرا ابزار CLI؟

قبل از هر چیز، بذارید بگم چرا CLI و نه یه کتابخانهٔ پایتون معمولی.

۱. سرعت: به‌جای نوشتن ۱۰ خط کد برای تبدیل تاریخ، فقط pdev date to-jalali 2024-03-21 می‌نویسی.

۲. جایی که کار می‌کنی: توی ترمینال، همون‌جایی که بقیهٔ کارها رو انجام می‌دی.

۳. قابل ترکیب: خروجی هر دستور، ورودی دستور بعدیه:

bash

curl -s https://api.github.com/users/torvalds | pdev jq .name -r
# Linus Torvalds

۴. زبان‌مستقل: هر کسی با هر زبانی می‌تونه ازش استفاده کنه.

چرا Typer و Rich؟

برای ساخت CLI در پایتون چند انتخاب داشتم: argparse (استاندارد ولی خسته‌کننده)، click (محبوب ولی verbose)، typer (مدرن، مبتنی بر type hints).

Typer رو انتخاب کردم چون با type hints کار می‌کنه و کد رو تمیز نگه می‌داره:

python

@app.command("to-jalali")
def to_jalali(
    value: str = typer.Argument(..., help="تاریخ میلادی به شکل YYYY-MM-DD."),
) -> None:
    """تبدیل تاریخ میلادی به شمسی."""
    g = parse_gregorian(value)
    j = gregorian_to_jalali(g)
    console.print(f"[green]{format_jalali(j)}[/green]")

و برای خروجی زیبا، Rich — جدول‌های رنگی، نوار پیشرفت، Syntax highlighting. نتیجه، CLI‌ای است که هم کار می‌کنه، هم زیباست.

۱۰ نسخه، ۶۲ دستور، ۵۸۱ تست

پروژه رو تدریجی و پله‌پله ساختم. هر نسخه یه حوزهٔ خاص رو پوشش می‌داد:

نسخهموضوعدستورات کلیدی1.0.0هستهٔ فارسیdate, text, number, uuid, json1.1.0فارسی پیشرفتهcalendar, transliterate, hijri, sort1.2.0شبکهip, dns, http, ping, port1.3.0متن پیشرفتهcount, frequency, extract, uniq1.4.0سیستمsys (disk, memory, cpu, top)1.5.0امنیتsecurity (JWT, hash, cert)1.6.0دیتابیسsqlite, csv-query1.7.0فارسی پیشرفته ۲fa (hamza, kashida, prefix)1.8.0خودکارسازیauto (batch, watch, cron)1.9.0رسانهpdf, audio2.0.0معماری extensibleshell, config, plugin

چند نمونهٔ واقعی از استفاده

۱. تبدیل تاریخ برای CV:

bash

$ pdev date to-jalali 2024-03-21
1403/01/02

۲. پاک‌سازی متن از Word:

bash

$ echo "می روم به خانه" | pdev text halfspace
می‌روم به خانه

۳. کوئری روی API بدون jq:

bash

$ curl -s https://api.github.com/repos/torvalds/linux | pdev jq .stargazers_count -r
187432

۴. ساخت QR برای متن فارسی:

bash

$ pdev qrcode "https://github.com/sobhanosmanzadeh1-beep/persian-devkit"

خروجی: یک QR Code که مستقیم در ترمینال نمایش داده می‌شه.

۵. شبیه‌سازی داده برای تست:

bash

$ pdev name profile -c 10 -j > users.json

فایل JSON با ۱۰ کاربر نمونهٔ فارسی، آمادهٔ استفاده در تست.

بزرگ‌ترین چالش: تست روی ویندوز

یکی از بزرگ‌ترین چالش‌ها، پشتیبانی از متن فارسی روی ویندوز بود. ویندوز به‌طور پیش‌فرض با کدپیج cp1252 کار می‌کنه، نه UTF-8. نتیجه:

cmd

> echo می روم | pdev text halfspace
?? ???

بعد از چند ساعت کلنجار رفتن، راه‌حل رو پیدا کردم:

python

if sys.platform == "win32":
    for stream in (sys.stdin, sys.stdout, sys.stderr):
        if hasattr(stream, "reconfigure"):
            stream.reconfigure(encoding="utf-8")

و در README برای کاربران ویندوز نوشتم: قبل از استفاده، chcp 65001 بزنن.

درس‌های مهمی که یاد گرفتم

۱. تست قبل از commit، نه بعدش.
هر بار که فکر می‌کردم «کد کار می‌کنه»، یه باگ کوچیک پیدا می‌شد. ۵۸۱ تست، ۸۲٪ پوشش — این آمار تصادفی نیست.

۲. انتشار نسخه‌های کوچیک، بهتر از یک نسخهٔ بزرگه.
به‌جای اینکه ۶ ماه وقت بذارم، هر ۱-۲ هفته یه نسخه منتشر کردم. کاربران زودتر بازخورد می‌دن.

۳. GitHub Actions یک نجات‌دهندهٔ واقعیه.
وقتی از ایران می‌خوای در PyPI منتشر کنی، IP بلاک می‌شی. راه‌حل: GitHub Actions از سرور آمریکا آپلود می‌کنه.

۴. مستندات فارسی، تمایز اصلیه.
اکثر پکیج‌های پایتون مستندات انگلیسی دارن. ولی وقتی کل README فارسی باشه، برای توسعه‌دهندهٔ ایرانی خیلی دلپذیرتره.

۵. جامعهٔ اوپن‌سورس فارسی، تشنهٔ ابزاره.
در این مدت چند پیام از توسعه‌دهندگان ایرانی گرفتم که می‌گفتن «دقیقاً همین رو لازم داشتم». این انگیزه‌بخش‌ترین بخش کاره.

الان کجای کاریم؟

نسخهٔ ۲.۰.۰ سه قابلیت بزرگ اضافه کرده:

۱. حالت تعاملی (REPL):

bash

$ pdev shell
╭─ ✨ pdev shell ─╮
│ 🧰 persian-devkit v2.0.0 — حالت تعاملی
│ دستورات داخلی: :help، :exit، :clear، :config، :plugins
╰──────────────────╯
pdev> date now
pdev> number words 1234
pdev> :exit

۲. فایل تنظیمات شخصی:

bash

$ pdev config set shell.banner false
$ pdev config get shell.prompt

۳. سیستم پلاگین:
هر کسی می‌تونه دستور دلخواهش رو اضافه کنه:

python

# ~/.pdev/plugins/myplugin.py
import typer
app = typer.Typer()

@app.command("hello")
def hello():
    print("سلام از پلاگین!")

بعدش pdev hello کار می‌کنه.

و اما نصب و شروع

bash

pip install persian-devkit

بعدش:

bash

pdev --help
pdev date now
pdev text halfspace "می روم"
pdev number words 1234
pdev qrcode "سلام دنیا"
pdev shell

پیوندها

• 🐍 PyPI: pypi.org/project/persian-devkit

• 🐙 GitHub: github.com/sobhanosmanzadeh1-beep/persian-devkit

• 📦 نسخهٔ فعلی: 2.0.0

• 🧪 ۵۸۱ تست، ۸۲٪ پوشش

• 📜 مجوز: MIT

در پایان

این پروژه به من یاد داد که ابزار خوب، اگر مفید باشه، دیده می‌شه. جامعهٔ فارسی‌زبان، تشنهٔ ابزارهای بومی‌ست. و ساختن چیز مفید برای دیگران، انگیزه‌بخش‌ترین کار دنیاست.

اگر این پروژه به کارت اومد، یه ⭐ توی GitHub بده. اگر باگ یا پیشنهادی داری، issue یا PR بفرست.

پ.ن. فصل اول پروژه در نسخهٔ ۲.۰.۰ بسته شد. فصل دوم با قابلیت‌هایی مثل pdev serve (API)، pdev tui (رابط گرافیکی) و pdev watch پیشرفته در راهه.