چرا از این فرمتکننده پایتون استفاده کنیم
- قالببندی به سبک بلک برای کد پایتون یکپارچه و نظرپردازانه
- طول خط قابل تنظیم برای کنترل پیچیدن خطوط طولانی
- قالببندی ایدِمپوتنت – اجرای مجدد روی کد قالببندیشده تغییری ایجاد نمیکند
- بازفرمت ایمن فاصلهها، تورفتگی و چیدمان بدون تغییر منطق
- ایدهآل برای بازبینی کد، درخواستهای ادغام و آموزش اعضای جدید تیم
- مستقیماً در ویرایشگر مرورگر با هایلایت سینتکس کار میکند
- سازگار با استفاده محلی از بلک تا قالببندی آنلاین و CI هماهنگ بمانند
🛠️ نحوه استفاده از قالببند پایتون for python-formatter
۱. کد پایتون خود را بچسبانید یا آپلود کنید
📥 کد خود را در ویرایشگر بچسبانید یا یک فایل `.py` را کشیده و رها کنید. قالببند فرض میکند پایتون از نظر نحوی معتبر است؛ اگر تجزیه شکست بخورد، به جای نتیجه قالببندیشده، خطا مشاهده خواهید کرد.
۲. (اختیاری) طول خط را تنظیم کنید
📏 از تنظیم طول خط برای انتخاب میزان پیچیدن خطوط طولانی استفاده کنید. مقادیر رایج ۸۸ (پیشفرض بلک)، ۱۰۰ یا ۱۲۰ برای مانیتورهای عریض هستند. اگر میخواهید پیچیدن بر اساس طول خط غیرفعال شود، آن را روی ۰ تنظیم کنید.
۳. کد خود را قالببندی کنید
✨ روی **قالببندی** کلیک کنید. ابزار کد شما را به یک بکاند ایمن به سبک بلک میفرستد که تورفتگی، خطوط خالی، فاصلهها و پیچیدن را نرمالسازی میکند در حالی که معناشناسی حفظ میشود.
۴. بازبینی، کپی یا دانلود
🔍 قبل/بعد را مستقیماً در مرورگر مقایسه کنید. وقتی از نتیجه راضی بودید، کد قالببندیشده را به پروژه خود برگردانید یا آن را به عنوان فایل `.py` آماده کامیت دانلود کنید.
مشخصات فنی
موتور قالببندی و سبک
این قالببند از قوانین نظرپردازانه به سبک بلک پیروی میکند تا کد پایتون شما در بین فایلها، ماشینها و ویرایشگرها یکسان به نظر برسد.
| جنبه | رفتار | یادداشتها |
|---|---|---|
| تورفتگی | ۴ فاصله در هر سطح | تبها در خروجی قالببندیشده به فاصله نرمالسازی میشوند. |
| نقلقول | سبک نقلقول یکپارچه | رشتهها ممکن است بازنویسی شوند (مثلاً از تکنقلقول به دو نقلقول) تا از یک سبک یکنواخت پیروی کنند. |
| واردات | گروهبندی و فاصلهدهی یکپارچه | کتابخانه استاندارد، واردات شخص ثالث و محلی در صورت لزوم با خطوط خالی از هم جدا شدهاند. |
| خطوط خالی | نرمالشده حول کلاسها و توابع | با جدا کردن بخشهای منطقی کد، خوانایی را بهبود میبخشد. |
| توانهمسانی | ورودی یکسان → خروجی یکسان | اجرای مکرر فرمتکننده تغییرات اضافی ایجاد نمیکند. |
طول خط و پیچیدن
پارامتر اصلی قابل پیکربندی، تنظیم پیچیدن/طول خط (که در گزینههای ابزار به `wrapLineLength` نگاشت شده) است. این پارامتر کنترل میکند که چگونه عبارات و لیستهای آرگومان طولانی در حالی که معناشناسی کد حفظ میشود، پیچیده میشوند.
| تنظیم | محدوده مقدار | اثر |
|---|---|---|
| wrapLineLength = 0 | 0 | بر اساس طول خط پیچیده نشود؛ فقط تغییرات حداقلی اعمال میشود. |
| wrapLineLength = 79 | 1–79 | سبک بسیار فشرده، مناسب برای ترمینالهای سختگیرانه یا نمایشگرهای باریک. |
| wrapLineLength = 80–100 | 80–100 | محدوده توصیهشده برای اکثر تیمهای مدرن؛ تعادل بین خوانایی و عرض را برقرار میکند. |
| wrapLineLength = 101–120 | 101–120 | طرحبندی آزادتر برای صفحهنمایشهای فوق عریض یا کدهای حاشیهنویسی شده سنگین. |
ورودیهای پشتیبانیشده و محدودیتها
فرمتکننده هدفش اسکریپتها و ماژولهای روزمره پایتون مورد استفاده در بکاندهای وب، رابطهای خط فرمان، علم داده و آموزش است.
| پارامتر | محدودیت / رفتار | یادداشتها |
|---|---|---|
| پسوند فایل | .py | بهترین برای اسکریپتهای مستقل، ماژولها و نقاط ورودی ساده بسته. |
| انواع MIME | text/x-python | توسط ویرایشگر و مدیریت آپلود ابزار برای تشخیص فایلهای پایتون استفاده میشود. |
| حداکثر اندازه ورودی | ≈ ۲ مگابایت منبع | فایلهای بسیار بزرگ بهتر است مستقیماً با Black در محیط شما فرمت شوند. |
| رمزگذاری | UTF-8 توصیه میشود | قبل از قالببندی، از رمزگذاریهای قدیمی (مانند latin-1) تبدیل کنید. |
مدل اجرا و ایمنی
قالببندی در یک بکاند امن انجام میشود، بنابراین میتوانید قوانین سبک Black را در مرورگر بدون نصب چیزی استفاده کنید.
| جنبه | رفتار | یادداشتها |
|---|---|---|
| موتور | قالببند پایتون سمت سرور (سبک Black) | رابط کاربری کد شما را با گزینههای انتخاب شده به `/api/python-formatter` ارسال میکند. |
| انتقال | HTTPS POST | کد منبع از طریق یک ارتباط رمزگذاری شده به بکاند قالببند ارسال میشود. |
| زمانبندی | حدود ۲۵ ثانیه | اگر قالببندی بیش از حد طول بکشد، درخواستها برای جلوگیری از فرآیندهای معطل لغو میشوند. |
| مدیریت خطا | پیامهای خطای واضح | خطاهای پایتون نامعتبر یا داخلی به عنوان متن خطای قابل خواندن به رابط کاربری بازگردانده میشوند. |
جایگزینهای خط فرمان با Black
برای همگامسازی گردش کار محلی خود با این قالببند آنلاین، Black را به virtualenv، ویرایشگر و خط لوله CI خود اضافه کنید.
لینوکس / 🍎 مک
نصب Black با استفاده از pip
pip install blackقالببند رسمی Black را در محیط پایتون فعال شما نصب میکند.
قالببندی یک فایل واحد
black app.pyفایل `app.py` را با استفاده از سبک پیشفرض Black بازنویسی میکند.
استفاده از طول خط سفارشی
black --line-length 100 app.pyطول خط پیشفرض را برای مطابقت با قراردادهای پروژه شما تغییر میدهد.
ویندوز (PowerShell / CMD)
نصب Black با راهانداز py
py -m pip install blackاز راهانداز `py` ویندوز برای افزودن Black به محیط شما استفاده میکند.
قالببندی یک پروژه کامل
black src/ tests/همه فایلهای پایتون در `src/` و `tests/` را به صورت بازگشتی قالببندی میکند.
یکپارچهسازی با pre-commit
pre-commit install && pre-commit run --all-filesBlack را به طور خودکار روی فایلهای مرحلهای قبل از هر commit اجرا میکند.
موارد استفاده عملی برای فرمتکننده پایتون
توسعه بکاند و API
پروژههای جنگو، FastAPI، فلاسک یا میکروسرویس خود را قابل خواندن و بازبینی نگه دارید.
- فرمتبندی را روی مدلها، نماها و روترها قبل از ادغام عادیسازی کنید.
- از فرمتکننده به عنوان آخرین مرحله قبل از باز کردن درخواست کشش استفاده کنید.
- یک سبک واحد را روی کدهای نوشته شده دستی و تولید شده اعمال کنید.
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item( item_id:int , q:str|None=None):
return {"item_id":item_id,"q":q}
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str | None = None) -> dict:
return {"item_id": item_id, "q": q}
علم داده و نوتبوکها
سلولهای اکتشافی جاپیتر را به اسکریپتهای پایتون تمیز تبدیل کنید که برای کنترل نسخه آماده هستند.
- زنجیرههای طولانی پانداس و خطوط لوله عددی را پاکسازی کنید.
- سبک را در سراسر نوتبوکها قبل از صادر کردن آنها به عنوان ماژولهای `.py` استاندارد کنید.
- کدهای صیقل داده شده را در گزارشها، پستهای وبلاگ و نوشتههای فنی ارائه دهید.
import pandas as pd
df = pd.read_csv("data.csv")
df["ratio"]=df["a"] /(df["b"]+1e-9)
df=df.sort_values("ratio",ascending=False)
import pandas as pd
df = pd.read_csv("data.csv")
df["ratio"] = df["a"] / (df["b"] + 1e-9)
df = df.sort_values("ratio", ascending=False)
آموزش و یادگیری پایتون
با فرمتبندی خودکار مثالها و تمرینها، به یادگیرندگان نشان دهید که پایتون اصیل چگونه به نظر میرسد.
- ارسالهای دانشآموزان را قبل از نمرهدهی پاکسازی کنید تا روی منطق و ساختار تمرکز شود.
- تفاوت بین «کار میکند» و «قابل خواندن» را با مقایسههای قبل/بعد نشان دهید.
- هنگام آموزش PEP 8 و ویژگیهای مدرن پایتون، از فرمتکننده به صورت زنده استفاده کنید.
x= 1
if x>0:
print("positive")
x = 1
if x > 0:
print("positive")
❓ Frequently Asked Questions
❓آیا فرمتکننده پایتون رفتار کد من را تغییر میدهد؟
📏هنگام فرمتبندی کد پایتون چه طول خطی را باید انتخاب کنم؟
🧹این چگونه با یک لینتر پایتون متفاوت است؟
🔒آیا چسباندن کد پایتون من در یک فرمتکننده آنلاین ایمن است؟
HTTPS به یک بکاند امن ارسال میشود و به صورت موقت برای فرمتبندی پردازش میشود. با این حال، به عنوان یک روش بهترین، باید از ارسال رمزهای عبور، کلیدهای API، دادههای شخصی یا منطق تجاری بسیار محرمانه به هر ابزار آنلاین خودداری کنید. برای پروژههای حساس، به جای آن Black را به صورت محلی یا در محیط CI خود اجرا کنید.⚙️آیا میتوانم این سبک را در خط لوله CI خود ادغام کنم؟
🐍کدام نسخههای پایتون توسط قالببندی سبک بلک پشتیبانی میشوند؟
Pro Tips
ویرایشگر خود (VS Code, PyCharm, Neovim و غیره) را پیکربندی کنید تا یک قالببند سبک بلک هنگام ذخیره اجرا شود تا فایلهای شما همیشه قبل از کامیت تمیز باشند.
بلک را به هوکهای پیشکامیت اضافه کنید تا هر کامیت به طور خودکار قالببندی شود و مخزن شما در طول زمان سازگار بماند.
از ارسال اسرار، اعتبارنامهها یا الگوریتمهای اختصاصی به هر قالببند آنلاین خودداری کنید. کدهای بسیار حساس را فقط در خطوط لوله قالببندی محلی یا مبتنی بر CI نگه دارید.
این قالببند را با یک لینتر (Ruff, Flake8, pylint) ترکیب کنید: قالببند چیدمان را مدیریت میکند، در حالی که لینتر واردات استفاده نشده، پیچیدگی و خطاهای بالقوه را شناسایی میکند.
تنظیمات طول خط را در این ابزار، پیکربندی محلی بلک و CI هماهنگ کنید تا با سبکهای متضاد مبارزه نکنید.
Additional Resources
Other Tools
- زیباکننده CSS
- زیباکننده HTML
- زیباکننده JavaScript
- زیباکننده PHP
- انتخابگر رنگ
- استخراجکننده اسپرایت
- دیکودر Base64
- انکودر Base64
- فرمتدهنده C#
- فرمتدهنده CSV
- Dockerfile Formatter
- فرمتدهنده Elm
- فرمتدهنده ENV
- فرمتدهنده Go
- فرمتدهنده GraphQL
- فرمتدهنده HCL
- فرمتدهنده INI
- فرمتدهنده JSON
- فرمتدهنده LaTeX
- فرمتدهنده Markdown
- فرمتدهنده Objective-C
- Php Formatter
- فرمتدهنده Proto
- فرمتدهنده Ruby
- فرمتدهنده Rust
- فرمتدهنده Scala
- فرمتدهنده اسکریپت شل
- فرمتدهنده SQL
- قالببندی SVG
- قالببندی Swift
- قالببندی TOML
- Typescript Formatter
- قالببندی XML
- قالببندی YAML
- قالببندی Yarn
- کوچککننده CSS
- Html Minifier
- Javascript Minifier
- کوچککننده JSON
- کوچککننده XML
- نمایشگر هدرهای HTTP
- PDF به متن
- تستکننده Regex
- بررسیکننده رتبه SERP
- جستجوی Whois