rich

التمهيدي باللغة الإنجليزية • 简体中文 التمهيدي • 正體中文 التمهيدي • Lengua española التمهيدي • Deutsche التمهيدي • Läs på svenska • 日本語 التمهيدي • 한국어 التمهيدي • Français التمهيدي • Schwizerdütsch التمهيدي • हिन्डी التمهيدي • الملف التمهيدي البرتغالي البرتغالي • الملف التمهيدي الإيطالي • الملف التمهيدي Русский • الملف التمهيدي الإندونيسي • الملف التمهيدي فارسی • الملف التمهيدي Türkçe • الملف التمهيدي Polskie

Rich هي مكتبة Python للنصوص الغنية والتنسيق الجميل في الوحدة الطرفية.

تسهل واجهة API الغنية إضافة اللون والنمط إلى مخرجات المحطة الطرفية. يمكن لـ Rich أيضًا عرض جداول جميلة، وأشرطة التقدم، وتخفيض السعر، والتعليمة البرمجية المصدرية المميزة لبناء الجملة، وعمليات التتبع، والمزيد - خارج الصندوق.

للحصول على مقدمة بالفيديو عن Rich، راجع موقع Calcode.io بواسطة @fishnets88.

انظر ماذا يقول الناس عن ريتش.

التوافق

يعمل Rich مع Linux وmacOS وWindows. يعمل اللون الحقيقي / الرموز التعبيرية مع Windows Terminal الجديد، وتقتصر المحطة الكلاسيكية على 16 لونًا. يتطلب Rich إصدار Python 3.8 أو إصدار أحدث.

يعمل Rich مع أجهزة الكمبيوتر المحمولة Jupyter دون الحاجة إلى تكوين إضافي.

التثبيت

قم بالتثبيت باستخدام pip أو مدير حزم PyPI المفضل لديك.

python -m pip install rich

قم بتشغيل ما يلي لاختبار الإخراج الغني على جهازك الطرفي:

python -m rich

طباعة غنية

لإضافة مخرجات غنية إلى تطبيقك بسهولة، يمكنك استيراد طريقة الطباعة الغنية، التي لها نفس التوقيع مثل وظيفة Python المضمنة. جرب هذا:

 from rich import print

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

رد غني

يمكن تثبيت Rich في Python REPL، بحيث تتم طباعة وإبراز أي بنيات بيانات بشكل جميل.

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

استخدام وحدة التحكم

لمزيد من التحكم في محتوى الوحدة الطرفية الغني، قم باستيراد كائن وحدة التحكم وإنشائه.

 from rich . console import Console

console = Console ()

يحتوي كائن وحدة التحكم على طريقة print تحتوي على واجهة مشابهة عمدًا لوظيفة print المضمنة. فيما يلي مثال للاستخدام:

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

كما قد تتوقع، سيؤدي هذا إلى طباعة "Hello World!" إلى المحطة. لاحظ أنه على عكس وظيفة print المضمنة، سيقوم Rich بتغليف النص ليتناسب مع عرض الوحدة الطرفية.

هناك عدة طرق لإضافة اللون والنمط إلى مخرجاتك. يمكنك تعيين نمط للمخرج بأكمله عن طريق إضافة وسيطة للكلمات الرئيسية style . هنا مثال:

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

سيكون الإخراج شيء مثل ما يلي:

يعد هذا أمرًا جيدًا لتصميم سطر من النص في المرة الواحدة. للحصول على تصميم أكثر دقة، يعرض Rich علامة خاصة تشبه في تركيب كود bbcode. هنا مثال:

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

يمكنك استخدام كائن وحدة التحكم لإنشاء مخرجات متطورة بأقل جهد. راجع مستندات Console API للحصول على التفاصيل.

فحص غني

لدى Rich وظيفة فحص يمكنها إنتاج تقرير عن أي كائن Python، مثل الفئة أو المثيل أو المدمج.

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

راجع مستندات الفحص للحصول على التفاصيل.

مكتبة غنية

يحتوي Rich على عدد من العناصر القابلة للعرض المضمنة التي يمكنك استخدامها لإنشاء مخرجات أنيقة في واجهة سطر الأوامر الخاصة بك ومساعدتك في تصحيح أخطاء التعليمات البرمجية الخاصة بك.

انقر فوق العناوين التالية للحصول على التفاصيل:

سجل

يحتوي كائن وحدة التحكم على أسلوب log() الذي له واجهة مشابهة لـ print() ولكنه يعرض أيضًا عمودًا للوقت الحالي والملف والخط الذي أجرى المكالمة. افتراضيًا، سيقوم Rich بتمييز بناء الجملة لهياكل Python وسلاسل repr. إذا قمت بتسجيل مجموعة (أي إملاء أو قائمة)، فسيقوم Rich بطباعتها بشكل جميل بحيث تتناسب مع المساحة المتوفرة. وفيما يلي مثال على بعض هذه الميزات.

 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_locals ، التي تقوم بإخراج جدول يحتوي على المتغيرات المحلية حيث تم استدعاء أسلوب السجل.

يمكن استخدام التابع log لتسجيل الدخول إلى الوحدة الطرفية للتطبيقات طويلة التشغيل مثل الخوادم، ولكنه أيضًا أداة مساعدة رائعة لتصحيح الأخطاء.

معالج التسجيل

يمكنك أيضًا استخدام فئة Handler المضمنة لتنسيق وتلوين الإخراج من وحدة التسجيل في Python. فيما يلي مثال على الإخراج:

الرموز التعبيرية

لإدراج رمز تعبيري في إخراج وحدة التحكم، ضع الاسم بين نقطتين. هنا مثال:

 >> > console . print ( ":smiley: :vampire: :pile_of_poo: :thumbs_up: :raccoon:" )
? ? ? ? ?

الرجاء استخدام هذه الميزة بحكمة.

الجداول

يمكن لـ Rich تقديم جداول مرنة بأحرف مربعة Unicode. هناك مجموعة كبيرة ومتنوعة من خيارات التنسيق للحدود والأنماط ومحاذاة الخلايا وما إلى ذلك.

تم إنشاء الرسوم المتحركة أعلاه باستخدام 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 )

وهذا ينتج الإخراج التالي:

لاحظ أنه يتم عرض ترميز وحدة التحكم بنفس طريقة print() و log() . في الواقع، أي شيء يمكن عرضه بواسطة Rich قد يتم تضمينه في الرؤوس/الصفوف (حتى الجداول الأخرى).

تعتبر فئة Table ذكية بما يكفي لتغيير حجم الأعمدة لتناسب العرض المتاح للمحطة، وتغليف النص كما هو مطلوب. إليك نفس المثال، مع جعل الوحدة الطرفية أصغر من الجدول أعلاه:

أشرطة التقدم

يمكن لـ Rich عرض أشرطة تقدم متعددة خالية من الوميض لتتبع المهام طويلة الأمد.

للاستخدام الأساسي، قم بلف أي تسلسل في وظيفة track وكرره على النتيجة. هنا مثال:

 from rich . progress import track

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

ليس من الصعب إضافة أشرطة تقدم متعددة. إليك مثال مأخوذ من المستندات:

قد يتم تكوين الأعمدة لإظهار أي تفاصيل تريدها. تتضمن الأعمدة المضمنة النسبة المئوية للاكتمال وحجم الملف وسرعة الملف والوقت المتبقي. إليك مثال آخر يوضح التنزيل قيد التقدم:

لتجربة ذلك بنفسك، راجع الأمثلة/downloader.py الذي يمكنه تنزيل عناوين URL متعددة في وقت واحد أثناء عرض التقدم.

حالة

في المواقف التي يصعب فيها حساب التقدم، يمكنك استخدام التابع الحالة الذي سيعرض الرسوم المتحركة والرسالة "الدوارة". لن تمنعك الرسوم المتحركة من استخدام وحدة التحكم كالمعتاد. هنا مثال:

 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" )

يؤدي هذا إلى إنشاء الإخراج التالي في المحطة.

تم استعارة الرسوم المتحركة الدوارة من cli-spinners. يمكنك تحديد القرص الدوار عن طريق تحديد معلمة spinner . قم بتشغيل الأمر التالي لرؤية القيم المتاحة:

 python -m rich.spinner

ينشئ الأمر أعلاه الإخراج التالي في المحطة:

شجرة

يمكن للأغنياء أن يصنعوا شجرة بخطوط إرشادية. تعتبر الشجرة مثالية لعرض بنية الملف أو أي بيانات هرمية أخرى.

يمكن أن تكون تسميات الشجرة عبارة عن نص بسيط أو أي شيء آخر يمكن أن يقدمه Rich. قم بتشغيل ما يلي للعرض التوضيحي:

 python -m rich.tree

يؤدي هذا إلى إنشاء الإخراج التالي:

راجع مثال Tree.py للحصول على برنامج نصي يعرض عرضًا شجريًا لأي دليل، على غرار أمر tree Linux.

أعمدة

يمكن لـ Rich عرض المحتوى في أعمدة مرتبة بعرض متساوٍ أو مثالي. إليك نسخة أساسية جدًا من الأمر ls (MacOS / Linux) الذي يعرض قائمة الدليل في الأعمدة:

 import os
import sys

from rich import print
from rich . columns import Columns

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

لقطة الشاشة التالية هي الناتج من مثال الأعمدة الذي يعرض البيانات المسحوبة من واجهة برمجة التطبيقات في الأعمدة:

تخفيض السعر

يستطيع Rich تقديم تخفيض السعر ويقوم بعمل معقول في ترجمة التنسيق إلى الجهاز.

لتقديم تخفيض السعر، قم باستيراد فئة 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 )

سيؤدي هذا إلى إنتاج شيء مثل ما يلي:

تسليط الضوء على بناء الجملة

يستخدم Rich مكتبة pygments لتنفيذ تمييز بناء الجملة. الاستخدام مشابه لتقديم تخفيض السعر؛ إنشاء كائن 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 )

سيؤدي هذا إلى إنتاج الإخراج التالي:

آثار

يمكن لـ Rich أن يقدم آثارًا جميلة يسهل قراءتها وإظهار المزيد من التعليمات البرمجية مقارنة بتتبعات Python القياسية. يمكنك تعيين Rich باعتباره معالج التتبع الافتراضي بحيث يتم عرض جميع الاستثناءات التي لم يتم اكتشافها بواسطة Rich.

إليك ما يبدو عليه نظام التشغيل OSX (مشابه لنظام التشغيل Linux):

تستفيد جميع العناصر القابلة للعرض من بروتوكول وحدة التحكم، والذي يمكنك استخدامه أيضًا لتنفيذ المحتوى الغني الخاص بك.

مؤشر سطر الأوامر الغني

راجع أيضًا Rich CLI للحصول على تطبيق سطر أوامر مدعوم من Rich. تسليط الضوء على بناء الجملة، وعرض تخفيض السعر، وعرض ملفات CSV في الجداول، والمزيد، مباشرة من موجه الأوامر.

نصية

راجع أيضًا المشروع الشقيق لـ Rich، Textual، والذي يمكنك استخدامه لإنشاء واجهات مستخدم متطورة في الجهاز.