Skip to content

Latest commit

 

History

History
494 lines (336 loc) · 22.4 KB

README.fa.md

File metadata and controls

494 lines (336 loc) · 22.4 KB

Supported Python Versions PyPI version

Downloads codecov Rich blog Twitter Follow

Logo

English readme简体中文 readme正體中文 readmeLengua española readmeDeutsche readmeLäs på svenska日本語 readme한국어 readmeFrançais readmeSchwizerdütsch readmeहिन्दी readmePortuguês brasileiro readmeItalian readmeРусский readmeفارسی readmeTürkçe readme

ریچ یک کتاب خانه پایتون برای متن های باشکوه و قالب بندی زیبا در ترمینال است.

ریچ افزودن رنگ و سبک به خروجی ترمینال را آسان می‌کند. ریچ همچنین می‌تواند جدول های زیبا، نوار های پیشرفت (progress bars), مارک داون (MarkDown), ترکیب سورس کد های برجسته شده, ردیاب ها (Tracebacks), و غیره را به صورت خودکار در ترمینال نمایش دهد.

قابلیت ها

برای معرفی ویدئویی ریچ این ویدئو را ببینید calmcode.io توسط @fishnets88.

ببینید مردم در مورد ریچ چه میگویند.

سازگاری

ریچ با لینوکس، مک او اس و ویندوز کار می کند. رنگ واقعی / ایموجی با ترمینال جدید ویندوز کار می کند، ترمینال کلاسیک به 16 رنگ محدود شده است. ریچ به پایتون 3.6.3 یا جدیدتر نیاز دارد.

ریچ با ژوپیتر نوت بوک (Jupyter notebooks) بدون نیازمندی اضافه ای کار می کند.

نصب کردن

با pip یا با مدیر بسته (package manager) مورد علاقه خودتان نصب کنید.

python -m pip install rich

برای آزمایش ریچ در ترمینال خودتان، این را اجرا کنید:

python -m rich

Rich Print

برای اضافه کردن راحت خروجی ریچ به برنامه خودتان، شما می توانید rich print را به پروژه خودتان اضافه (Import) کنید که اثر یکسانی مشابه تابع داخلی پایتون دارد. این قطعه کد را امتحان کنید:

from rich import print

print("Hello, [bold magenta]World[/bold magenta]!", ":vampire:", locals())

Hello World

Rich REPL

ریچ می تواند در Python REPL, نصب شود. که هر نوعی از اطلاعات را به زیبایی چاپ می کند و به زیبایی برجسته می کند.

>>> from rich import pretty
>>> pretty.install()

REPL

استفاده از Console

برای پایش بیشتر از محتوای ترمینال ریچ، Console را اضافه (Import) کنید و یک شیء (Object) بسازید.

from rich.console import Console

console = Console()

شی Console یک تابع با نام print دارد که مشابه تابع print داخلی پایتون است. کد زیر یک مثال از استفاده آن است:

console.print("Hello", "World!")

همانطور که احتمالا انتظار داشتید، این کد در ترمینال "Hello World!" چاپ می کند. در نظر داشته باشید که این شبیه به تابع print داخلی پایتون نیست. ریچ متن شما را به صورت کلمه‌ای (واژه بندی شده) در نظر میگیرد تا در عرض (width) ترمینال قرار بگیرد.

اینها تعدادی راه برای افزودن رنگ و سبک (Style) به خروجی خودتان است. شما می توانید با اضافه کردن کلمه کلیدی style برای خروجی های خود سبک و استایل در نظر بگیرید. کد زیر مثال استفاده از آن است:

console.print("Hello", "World!", style="bold red")

خروجی چیزی شبیه به این است:

Hello World

تا اینجا برای سبک و استایل دادن به یک خط خوب است. برای سبکی با دانه بندی (Finely Grained Styling)، ریچ یک نشانه گذاری خاص ارائه می دهند که چیزی شبیه به bbcode است. مثال آن به صورت زیر است:

console.print("Where there is a [bold cyan]Will[/bold cyan] there [u]is[/u] a [i]way[/i].")

Console Markup

شما می توانید از یک شیء Console برای تولید خروجی پیچیده، با کمترین تلاش استفاده کنید. برای جزئیات بیشتر به Console API مراجعه کنید.

Rich Inspect

ریچ دارای یک تابع inspect است که می تواند یک گزارش از هر شیء از پایتون، مثل کلاس (Class)، نمونه (Instance) یا توابع (Builtin) را تولید کند.

>>> my_list = ["foo", "bar"]
>>> from rich import inspect
>>> inspect(my_list, methods=True)

Log

برای جزئیات بیشتر به inspect docs مراجعه کنید.

Rich Library

ریچ شامل تعدادی از توابع قابل اجرا داخلی است که شما می توانید برای ایجاد خروجی برازنده و مناسب در ترمینال (CLI) خود استفاده کنید و به شما برای تصحیح (Debug) کد کمک می کند.

برای جزئیات بیشتر روی سر فصل های زیر کلیک کنید:

Log

شیء Console دارای یک تابع ()log است که رفتاری مشابه ()print دارد، اما همچنین یک ستون برای نمایش زمان، فایل مربوطه و شماره خطِ کدِ اجرا شده در نظر می گیرد. به صورت پیشفرض، ریچ علائم (syntax) را برای ساختار های پایتون و برای رشته (String) های repr برجسته می کند. اگر شما یک مجموعه (دیکشنری یا لیست) را چاپ کنید، ریچ به زیبایی آن را در فضای موجود چاپ می کند. مثال زیر نمایش برخی ویژگی های آن است:

from rich.console import Console
console = Console()

test_data = [
    {"jsonrpc": "2.0", "method": "sum", "params": [None, 1, 2, 4, False, True], "id": "1",},
    {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
    {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": "2"},
]

def test_log():
    enabled = False
    context = {
        "foo": "bar",
    }
    movies = ["Deadpool", "Rise of the Skywalker"]
    console.log("Hello from", console, "!")
    console.log(test_data, log_locals=True)


test_log()

قطعه کد بالا، خروجی زیر را تولد می کند:

Log

به متغیر های log_locals توجه کنید، جایی که تابع log صدا زده می شود، یک جدول که شامل متغیر های محلی است در خروجی نمایش داده می شود.

تابع log میتواند برای گزارش گیری در ترمینال برای برنامه هایی با اجراهای طولانی مدت، مثل سرور استفاده شود؛ اما همچنین کمک بسیار مناسب و خوبی برای تصحیح (debugging) برخی خطاهاست.

Logging Handler

همچنین شما می توانید از Handler class های داخلی برای فرمت دادن و رنگی کردن خروجی از ماژول گزارش پایتون (Python's logging module) استفاده کنید. کد زیر یک مثال از خروجی را نشان می دهد:

Logging

Emoji

برای افزودن یک ایموجی به خروجی ترمینال، اسم آن را بین دو نقطه (colon) قرار دهید. قطعه کد زیر مثال آن است:

>>> console.print(":smiley: :vampire: :pile_of_poo: :thumbs_up: :raccoon:")
😃 🧛 💩 👍 🦝

لطفا از این ویژگی خردمندانه و عاقلانه استفاده کنید.

Tables

ریچ توانایی آن را دارد که جداول انعطاف پذیری را با کارکتر های یونیکد (unicode) بسازد.

table movie

انیمشن بالا با استفاده از table_movie.py در دایرکتوری (پوشه) تست ساخته شده است.

این یک مثال ساده از جدول است:

from rich.console import Console
from rich.table import Table

console = Console()

table = Table(show_header=True, header_style="bold magenta")
table.add_column("Date", style="dim", width=12)
table.add_column("Title")
table.add_column("Production Budget", justify="right")
table.add_column("Box Office", justify="right")
table.add_row(
    "Dec 20, 2019", "Star Wars: The Rise of Skywalker", "$275,000,000", "$375,126,118"
)
table.add_row(
    "May 25, 2018",
    "[red]Solo[/red]: A Star Wars Story",
    "$275,000,000",
    "$393,151,347",
)
table.add_row(
    "Dec 15, 2017",
    "Star Wars Ep. VIII: The Last Jedi",
    "$262,000,000",
    "[bold]$1,332,539,889[/bold]",
)

console.print(table)

این کد خروجی زیر را تولید می کند:

table

توجه داشته باشید که نشانه گذاری کنسول به همان روش print() و log() پردازش می شود. در واقع، هر چیزی که توسط Rich قابل رندر است در هدرها / ردیف ها (حتی جداول دیگر) ممکن است گنجانده شود.

کلاس Table به اندازه کافی هوشمند است که اندازه ستون ها را متناسب با عرض موجود ترمینال تغییر دهد و متن را در صورت لزوم بسته بندی کند. این همان مثال با ترمینال کوچکتر از جدول بالاست:

table2

Progress Bars

ریچ می تواند چندین نوار پیشرفت (progress) را بدون ناهماهنگی و اختلال برای پیگیری وظایف طولانی مدت پردازش کند.

برای استفاده اولیه، هر دنباله ای را در تابع track بسته بندی کنید و روی نتیجه تکرار کنید. مثال آن به صورت زیر است:

from rich.progress import track

for step in track(range(100)):
    do_step(step)

اضافه کردن چندین نوار پیشرفت خیلی سخت نیست. مثال آن که برگرفته از اسناد و داکیومنت میباشد به صورت زیر است:

progress

ستون ها ممکن است به گونه ای پیکربندی شوند که جزئیاتی را که می خواهید نشان دهند. ستون های از پیش تعیین شده شامل درصد کامل شده، اندازه فایل، سرعت فایل و زمان باقی مانده است. در زیر مثال دیگری وجود دارد که دانلود در حال انجام را نشان می دهد:

progress

برای اینکه خودتان این را امتحان کنید، فایل examples/downloader.py را ببینید که می‌تواند چندین لینک URL را به طور همزمان بارگیری کند و پیشرفت را نشان دهد.

Status

برای موقعیت هایی که محاسبه پیشرفت، دشوار است، می توانید از روش status استفاده کنید که یک پیام و یک انیمیشن چرخنده (spinner) را نمایش می‌دهد. این انیمیشن شما را از استفاده عادی از کنسول باز نمی دارد. مثال آن به صورت زیر است:

from time import sleep
from rich.console import Console

console = Console()
tasks = [f"task {n}" for n in range(1, 11)]

with console.status("[bold green]Working on tasks...") as status:
    while tasks:
        task = tasks.pop(0)
        sleep(1)
        console.log(f"{task} complete")

این کد خروجی زیر را در ترمینال ایجاد می کند.

status

در انیمیشن های چرخنده از cli-spinners استفاده شده است. شما می توانید با تعیین پارامتر spinner یک چرخنده را انتخاب کنید. برای مشاهده موارد موجود، دستور زیر را اجرا کنید:

python -m rich.spinner

دستور بالا خروجی زیر را در ترمینال ایجاد می کند:

spinners

Tree

ریچ می تواند یک tree را با خطوط راهنما نمایش دهد. یک درخت برای نمایش ساختار فایل یا هر داده سلسله مراتبی دیگر مناسب است.

برچسب (labels) های درخت می توانند متن ساده یا هر چیز دیگری که ریچ می تواند نمایش دهد باشد. برای نمایش موارد گفته شده دستور زیر را اجرا کنید:

python -m rich.tree

این کد خروجی زیر را ایجاد می کند:

markdown

مثال tree.py را برای اسکریپتی ببینید که نمایش درختی از هر دایرکتوری را نمایش می دهد، شبیه به فرمان tree در لینوکس است.

Columns

ریچ می تواند محتوا را به صورت columns مرتب با عرض مساوی یا بهینه ارائه دهد. مثال زیر یک شبیه سازی بسیار ابتدایی از دستور ls در (مک او اس / لینوکس) است که فهرست دایرکتوری را در ستون ها نمایش می دهد:

import os
import sys

from rich import print
from rich.columns import Columns

directory = os.listdir(sys.argv[1])
print(Columns(directory))

تصویر زیر خروجی columns example است که داده های استخراج شده از یک API را در ستون ها نمایش می دهد:

columns

Markdown

ریچ میتواند markdown را پردازش کند و کار مناسبی را برای فرمت بندی آن در ترمینال انجام میدهد.

برای پردازش markdown کافی است تا کلاس Markdown آنرا فرا خوانی کرده و یک شی از آن را بسازید و متن حاوی markdown را به آن بدهید. در نهایت آنرا در کنسول و ترمینال چاپ کنید. مثال آن به صورت زیر است:

from rich.console import Console
from rich.markdown import Markdown

console = Console()
with open("README.md") as readme:
    markdown = Markdown(readme.read())
console.print(markdown)

خروجی کد بالا چیزی شبیه به تصویر زیر را تولید می کند:

markdown

Syntax Highlighting

ریچ از کتابخانه pygments برای پیاده سازیsyntax highlighting استفاده می کند. استفاده از آن مشابه پردازش markdown هاست؛ یک شی Syntax بسازید و آن را برای کنسول چاپ کنید. مثال آن به صورت زیر است:

from rich.console import Console
from rich.syntax import Syntax

my_code = '''
def iter_first_last(values: Iterable[T]) -> Iterable[Tuple[bool, bool, T]]:
    """Iterate and generate a tuple with a flag for first and last value."""
    iter_values = iter(values)
    try:
        previous_value = next(iter_values)
    except StopIteration:
        return
    first = True
    for value in iter_values:
        yield first, False, previous_value
        first = False
        previous_value = value
    yield first, True, previous_value
'''
syntax = Syntax(my_code, "python", theme="monokai", line_numbers=True)
console = Console()
console.print(syntax)

این کد خروجی زیر را ایجاد می کند:

syntax

Tracebacks

ریچ می تواند tracebacks های زیبایی را نمایش دهد که خواندن آن آسان تر است و کد بیشتری را نسبت به traceback های استاندارد پایتون نشان می دهد. شما می توانید ریچ را به عنوان کنترل کننده اصلی tracebacks تنظیم کنید تا همه استثناهای کشف نشده توسط ریچ ارائه شوند.

در مک او اس به صورت زیر نمایش داده می شود (در لینوکس نیز مشابه این است):

traceback

همه ریچ های قابل نمایش از Console Protocol استفاده می کنند، بنابراین شما می توانید برای پیاده سازی محتوای ریچ خود نیز از آن استفاده کنید.

Rich CLI

همچنین Rich CLI را که برای برنامه های دستوری (command line)، توسط Rich ساخته شده است ببینید. برجسته سازی کد (Syntax highlight code)، پردازش کردن مارک دون، نمایش فایل های CSV در جدول ها و موارد بیشتر، به صورت مستقیم از خط فرمان و ترمینال.

Rich CLI

Textual

همچنین (پروژه) خواهر ریچ Textual را ببینید، که با استفاده از آن شما می توانید رابط های کاربری پیچیده را در ترمینال بسازید.

Textual screenshot

پروژه هایی که از ریچ استفاده می کنند

برای دیدن چند نمونه از پروژه هایی که از ریچ استفاده می کنند، به Rich Gallery در Textualize.io سر بزنید.

آیا می خواهید پروژه خودتان را به گالری اضافه کنید؟ شما می توانید! کافیست از این دستورات پیروی کنید.