# قالب‌بندی‌کننده Python

URL: https://discuvr.org/python-formatter/?hl=fa
Last updated: 2026-11-07
MCP tool: `format_python`

کد Python را بچسبانید تا Black آن را با طول خط دلخواهتان قالب‌بندی کند. خطای نحوی شماره خط دقیق را نشان می‌دهد. کد هرگز اجرا یا ذخیره نمی‌شود.

این ابزار Black - قالب‌بندگری که بیشتر پروژه‌های Python از پیش بر آن توافق دارند - را روی هر چه جای‌گذاری کنید اجرا می‌کند، با طول خط و نحوه برخورد با علامت نقل‌قول که خودتان انتخاب می‌کنید. اگر فایل تحلیل نشود، می‌گوید در کدام خط، و اگر از قبل قالب‌بندی‌شده باشد، آن را هم می‌گوید، به‌جای وانمود کردن که کاری انجام داده است.

## عملکرد

- قالب‌بندی Black در 79، 88، 100 یا 120 ستون.
- حالت "فقط بررسی": بدون تغییر فایل، بفهمید که آیا تغییر می‌کرد یا نه.
- سبک علامت نقل‌قول خودتان را حفظ کنید، یا بگذارید Black آن را یکسان‌سازی کند.
- کامای پایانی جادویی که یک مجموعه را باز نگه می‌دارد را رعایت یا نادیده بگیرید.
- وقتی نحو به نسخه حساس است، نسخه‌ای خاص از Python را هدف بگیرید.
- خطاهای نحوی خط، ستون و کد اطراف را گزارش می‌دهند.
- گزارش می‌دهد چند خط افزوده و حذف شده است، به‌علاوه شکل فایل.

## نحوه کار

1. کد، یا یک فایل کامل از آن را جای‌گذاری کنید.
2. طول خط و هر گزینه‌ای که برایتان مهم است را انتخاب کنید.
3. روی قالب‌بندی بزنید، سپس نتیجه را کپی یا دانلود کنید.

## کد شما هرگز اجرا نمی‌شود

قالب‌بندی Python نیازی به اجرای آن ندارد. کد به یک درخت نحوی تحلیل و از همان درخت، کاملاً در حافظه، بازنویسی می‌شود - هرگز در فایلی نوشته نمی‌شود، هرگز وارد نمی‌شود و هرگز اجرا نمی‌شود. قالب‌بندی که آنچه جای‌گذاری کرده‌اید را اجرا کند، یک پوسته فرمان راه‌دور با یک کادر متنی خواهد بود.

## چرا Black، و نه نظری از خودمان

Black تبدیلی است که درخت نحوی انتزاعی (AST) را حفظ می‌کند: کدی که بیرون می‌آید همان برنامه کدی است که وارد شده. این ویژگی تمام دلیل قابل‌اعتماد بودن یک قالب‌بند است، و دلیل این است که هیچ مدل زبانی در هیچ بخشی از این ابزار دخالت ندارد. مدلی که از او خواسته شود کد را مرتب کند، گاهی یک خط را در همان حین بازنویسی می‌کند، و تغییر خاموش در کدی که کار می‌کند، تنها شکستی است که یک قالب‌بند نمی‌تواند بپذیرد.

## فقط بررسی

همان سؤالی که CI می‌پرسد: آیا این فایل تغییر می‌کرد؟ حالت بررسی کد اصلی شما را بدون تغییر برمی‌گرداند و می‌گوید آیا Black آن را دوباره قالب‌بندی می‌کرد و در چند خط. این راه سریعی برای فهمیدن این است که چرا یک پایپ‌لاین روی فایلی که نمی‌توانید به‌صورت محلی بازتولید کنید شکست می‌خورد.

## کامای انتهایی جادویی و fmt: off، مثال‌های حل‌شده

کاما بعد از آخرین عنصر به Black می‌گوید یک فراخوانی یا مجموعه را با یک عنصر در هر سطر نگه دارد: result = compute(alpha, beta,) در چهار سطر برمی‌گردد و alpha, و beta, هر کدام در سطر جداگانه‌اند. گزینه نادیده گرفتن کامای انتهایی جادویی را تیک بزنید تا همان ورودی، هر جا در طول سطر جا شود، به result = compute(alpha, beta) تبدیل شود. برای محافظت از بلوکی که دستی تراز شده، مثل یک ماتریس، # fmt: off را در سطر بالای آن و # fmt: on را زیر آن بگذارید تا Black همه چیزِ میان آن‌ها را همان‌طور که نوشته‌اید رها کند؛ # fmt: skip در انتهای یک سطر فقط همان سطر را حفظ می‌کند. این‌ها توضیحات خود Black هستند، پس وقتی CI پروژه‌تان Black را اجرا می‌کند هم کار می‌کنند.

## سوالات

**آیا کد من آپلود یا ذخیره می‌شود؟**

به سرور فرستاده می‌شود، در حافظه قالب‌بندی می‌شود و در همان پاسخ برگردانده می‌شود. هیچ‌چیز روی دیسک نوشته، کش یا ثبت نمی‌شود، و رکورد استفاده فقط شمارش‌ها را نگه می‌دارد - اندازه، گزینه‌ها، چند خط تغییر کرده - و هرگز خود کد را نه.

**آیا قالب‌بندی چیزی را که کد من انجام می‌دهد تغییر می‌دهد؟**

نه. Black چیدمان را تغییر می‌دهد نه رفتار را، اما کاری بیش از جابه‌جا کردن فاصله‌ها می‌کند. پرانتزهای زائد را حذف می‌کند (x = (1) به x = 1 تبدیل می‌شود)، پیشوندها و توان‌های اعداد را با حروف کوچک می‌نویسد (0XABCDEF به 0xABCDEF و 1E5 به 1e5)، وقتی یک فراخوانی را در چند خط می‌شکند ویرگول پایانی اضافه می‌کند، خط‌های خالی پشت سر هم را کم می‌کند و فاصله‌های داخل docstring را حذف می‌کند (""" Doc. """ به """Doc."""). این تغییر آخر متن __doc__ را عوض می‌کند، که فقط وقتی مهم است که کد شما docstringهای خودش را بخواند.

**چرا فایل من اصلاً دوباره قالب‌بندی نشد؟**

چون از قبل با طول خطی که انتخاب کرده بودید قالب‌بندی شده بود. ابزار می‌گوید "از قبل قالب‌بندی‌شده" به‌جای برگرداندن بی‌صدای یک کپی.

**آیا وارد کردنی‌های من را مرتب می‌کند؟**

نه. مرتب‌سازی وارد کردنی‌ها کار isort است، نه Black، و این دو به اندازه کافی با هم اختلاف دارند که اگر این‌جا انجام می‌شد شما را شگفت‌زده می‌کرد.

**آیا می‌تواند فایلی با خطای نحوی را قالب‌بندی کند؟**

هیچ قالب‌بندی نمی‌تواند - فایلی که تحلیل نمی‌شود، ساختاری برای بازنویسی ندارد. خط، ستون و کد اطراف را دریافت می‌کنید تا بتوانید آن را اصلاح و دوباره تلاش کنید.

**آیا از PEP 8 پیروی می‌کند؟**

Black با یک انحراف شناخته‌شده با PEP 8 سازگار است: طول خط پیش‌فرض آن 88 است، نه 79. اگر به رقم سخت‌گیرانه‌تر نیاز دارید، 79 را در انتخاب‌گر طول خط انتخاب کنید.

**چه اندازه فایلی را می‌توانم قالب‌بندی کنم؟**

تا 400,000 نویسه در هر اجرا. قالب‌بندی پس از 10 ثانیه متوقف می‌شود، که فقط فایل‌های بسیار بزرگ یا بسیار تکراری به آن می‌رسند، و هر نشانی IP می‌تواند هر 10 دقیقه 30 بار قالب‌بندی کند.

**چطور همین قالب‌بندی را در ویرایشگر، pre-commit یا CI بگیرم؟**

این صفحه از Black استفاده می‌کند و نسخه‌اش در صفحه‌های عریض در سربرگ بالای صفحه نمایش داده می‌شود. Black تنظیمات پروژه را از pyproject.toml در بخش [tool.black] با نام‌های بلند گزینه‌ها می‌خواند: line-length = 88 برای گزینه "طول خط" که انتخاب کرده‌اید، skip-string-normalization = true اگر "حفظ نقل‌قول‌های من" را تیک زده‌اید، skip-magic-trailing-comma = true برای "نادیده گرفتن کامای انتهایی جادویی" و target-version = ["py311"] برای مقدار ثابت در "هدف". افزونه‌های ویرایشگر و هوک pre-commit همین فایل را می‌خوانند. برای قالب‌بندی black . و در CI دستور black --check --diff . را اجرا کنید: چیزی را تغییر نمی‌دهد و اگر فایلی دوباره قالب‌بندی شود با کد 1 خارج می‌شود. همان نسخه Black این صفحه را ثابت کنید، چون نخستین انتشار هر سال میلادی ممکن است سبک پایدار را تغییر دهد.

**آیا خروجی با قالب‌بند Ruff (ruff format) یکسان است؟**

تقریباً همیشه، اما نه بایت به بایت. قالب‌بند Ruff طوری طراحی شده که مستقیماً جایگزین Black شود و مستندات Ruff می‌گوید در پروژه‌های بزرگی که با Black قالب‌بندی شده‌اند، مانند Django و Zulip، بیش از 99.9% خطوط یکسان درمی‌آیند. در کدی که هرگز از Black رد نشده، به‌ویژه در توضیحات پایان خط، تفاوت بیشتری دارد و مستنداتش تفاوت‌های عمدی را فهرست می‌کند. طول خط پیش‌فرض آن هم 88 است و با line-length در [tool.ruff] تنظیم می‌شود؛ quote-style = "preserve" در [tool.ruff.format] معادل "حفظ نقل‌قول‌های من" و skip-magic-trailing-comma = true معادل "نادیده گرفتن کامای انتهایی جادویی" است. اگر CI شما ruff format --check را اجرا می‌کند، فایل را با Ruff آزمایش کنید، نه با این صفحه.

## بیشتر در ابزارهای برنامه‌نویسان

- [نمایش‌دهنده HTML](https://discuvr.org/html-viewer/?hl=fa)
- [ماشین‌حساب زیرشبکه IP](https://discuvr.org/ip-subnet-calculator/?hl=fa)
- [رمزگذاری / رمزگشایی](https://discuvr.org/encode-decode/?hl=fa)
- [مبدل مهر زمانی Unix](https://discuvr.org/timestamp-converter/?hl=fa)

## اغلب همراه با این‌ها استفاده می‌شود

- [مقایسه متن](https://discuvr.org/text-diff/?hl=fa)
- [مبدل حالت حروف و ابزارهای خط](https://discuvr.org/case-converter/?hl=fa)
- [Study Buddy](https://discuvr.org/study-buddy/?hl=fa)

---

Part of Discuvr (https://discuvr.org/): Discuvr is a collection of free, focused tools for day-to-day professional work - office and data utilities, legal and compliance helpers, privacy and security checks, and developer formatters. Every tool has its own page, and most can also be called from ChatGPT or Claude over MCP.