compileall --- کامپایل بایتی کتابخانه‌های پایتون

کد منبع: Lib/compileall.py

این ماژول چند تابع کاربردی برای پشتیبانی از نصب کتابخانه‌های پایتون فراهم می‌کند. این توابع، پرونده‌های مبدأ پایتون را در یک درخت پوشه کامپایل می‌کنند. از این ماژول می‌توان برای ایجاد پرونده‌های بایت‌کدِ نهان‌شده در زمان نصب کتابخانه استفاده کرد؛ به‌گونه‌ای که این پرونده‌ها حتی برای کاربرانی که اجازه‌ی نوشتن در پوشه‌های کتابخانه را ندارند نیز قابل استفاده باشند.

دسترس‌پذیری: not WASI.

این ماژول در WebAssembly کار نمی‌کند یا در دسترس نیست. برای اطلاعات بیشتر سکوهای WebAssembly را ببینید.

استفاده از خط فرمان

این ماژول می‌تواند به‌عنوان یک اسکریپت (با استفاده از python -m compileall) برای کامپایل پرونده‌های منبع پایتون کار کند.

directory ...
file ...

آرگومان‌های جایگاهی، پرونده‌هایی برای کامپایل یا پوشه‌هایی هستند که حاوی پرونده‌های منبع بوده و به‌صورت بازگشتی پیمایش می‌شوند. اگر آرگومانی داده نشود، به‌گونه‌ای رفتار می‌کند که گویی خط فرمان -l <directories from sys.path> بوده است.

-l

به‌صورت بازگشتی وارد زیرپوشه‌ها نشوید، فقط پرونده‌های کد منبعی را که مستقیماً در پوشه‌های نام‌برده‌شده یا ضمنی قرار دارند، کامپایل کنید.

-f

بازسازی اجباری، حتی اگر برچسب‌های زمانی به‌روز باشند.

-q

فهرست پرونده‌های کامپایل‌شده را چاپ نکنید. اگر یک بار داده شود، پیام‌های خطا همچنان چاپ می‌شوند. اگر دو بار داده شود (-qq)، تمام خروجی سرکوب می‌شود.

-d destdir

پوشه‌ای که به ابتدای مسیر هر پرونده در حال کامپایل افزوده می‌شود. این پوشه در ردگیری‌های پشته در زمان کامپایل ظاهر می‌شود و همچنین به‌صورت کامپایل‌شده در پرونده بایت‌کد نیز گنجانده می‌شود؛ جایی که از آن در ردگیری‌های پشته و سایر پیام‌ها در مواردی استفاده خواهد شد که پرونده منبع در زمان اجرای پرونده بایت‌کد وجود ندارد.

-s strip_prefix

پیشوند داده‌شده را از مسیرهای ثبت‌شده در پرونده‌های .pyc حذف کنید. مسیرها نسبت به پیشوند نسبی می‌شوند.

این گزینه با -p قابل استفاده است، اما با -d قابل استفاده نیست.

-p prepend_prefix

پیشوند داده‌شده را به ابتدای مسیرهای ثبت‌شده در پرونده‌های .pyc اضافه کنید. برای مطلق کردن مسیرها، از -p / استفاده کنید.

این گزینه را می‌توان با -s استفاده کرد، اما با -d نمی‌توان.

-x regex

از عبارت باقاعده (regex) برای جست‌وجوی مسیر کامل هر پرونده در نظر گرفته‌شده برای کامپایل استفاده می‌شود، و اگر عبارت باقاعده تطابقی ایجاد کند، از آن پرونده صرف‌نظر می‌شود.

-i list

پرونده list را بخوانید و هر خط موجود در آن را به فهرست پرونده‌ها و پوشه‌ها برای کامپایل اضافه کنید. اگر list برابر - باشد، سطرها را از stdin بخوانید.

-b

پرونده‌های بایت‌کد را در محل‌ها و نام‌های قدیمی خود بنویسید؛ این کار ممکن است پرونده‌های بایت‌کد ایجادشده توسط نسخه دیگری از پایتون را بازنویسی کند. به‌طور پیش‌فرض، پرونده‌ها در محل‌ها و نام‌های PEP 3147 خود نوشته می‌شوند، که امکان هم‌زیستی پرونده‌های بایت‌کد از چندین نسخه پایتون را فراهم می‌کند.

-r

حداکثر سطح بازگشت برای زیرپوشه‌ها را کنترل می‌کند. اگر این گزینه داده شود، گزینه -l در نظر گرفته نخواهد شد. python -m compileall <directory> -r 0 معادل python -m compileall <directory> -l است.

-j N

برای کامپایل پرونده‌های درون پوشه داده‌شده از N کارگر استفاده کنید. اگر از 0 استفاده شود، از نتیجه‌ی os.process_cpu_count() استفاده خواهد شد.

--invalidation-mode [timestamp|checked-hash|unchecked-hash]

نحوه‌ی ابطال پرونده‌های بایت‌کد تولیدشده در ران‌تایم را کنترل می‌کند. مقدار timestamp به این معناست که پرونده‌های .pyc با برچسب زمانی و اندازه‌ی پرونده منبع به‌صورت تعبیه‌شده تولید می‌شوند. مقادیر checked-hash و unchecked-hash موجب تولید پرونده‌های pyc مبتنی بر هش می‌شوند. پرونده‌های pyc مبتنی بر هش، به‌جای برچسب زمانی، یک هش از محتوای پرونده منبع را تعبیه می‌کنند. برای اطلاعات بیشتر درباره‌ی نحوه‌ی اعتبارسنجی پرونده‌های نهانگاه بایت‌کد توسط پایتون در ران‌تایم، بی‌اعتبارسازی بایت‌کد نهان‌شده را ببینید. مقدار پیش‌فرض در صورتی که متغیر محیطی SOURCE_DATE_EPOCH تنظیم‌نشده باشد، timestamp است، و در صورتی که متغیر محیطی SOURCE_DATE_EPOCH تنظیم‌شده باشد، checked-hash است.

-o level

با سطح بهینه‌سازی داده‌شده کامپایل کنید. می‌توانید چند بار از آن استفاده کنید تا همزمان برای چند سطح کامپایل شود (برای مثال، compileall -o 1 -o 2).

-e dir

پیوندهای نمادین اشاره‌کننده به بیرون از پوشه‌ی داده‌شده را نادیده بگیرید.

اگر دو پرونده .pyc با سطوح بهینه‌سازی متفاوت محتوای یکسانی داشته باشند، برای یکپارچه‌سازی پرونده‌های تکراری از پیوندهای سخت استفاده کنید.

تغییر یافته در نسخه‌ی 3.2: گزینه‌های -i، -b و -h اضافه شدند.

تغییر یافته در نسخه‌ی 3.5: گزینه‌های -j، -r و -qq افزوده شدند. گزینه‌ی -q به یک مقدار چندسطحی تغییر یافت. -b همیشه یک پرونده بایت‌کد تولید خواهد کرد که به .pyc ختم می‌شود، هرگز به .pyo ختم نخواهد شد.

تغییر یافته در نسخه‌ی 3.7: گزینه --invalidation-mode افزوده شد.

تغییر یافته در نسخه‌ی 3.9: گزینه‌های -s، -p، -e و --hardlink-dupes افزوده شدند. محدودیت بازگشت پیش‌فرض از ۱۰ به sys.getrecursionlimit() افزایش یافت. امکان تعیین گزینه‌ی -o چندین بار افزوده شد.

هیچ گزینه‌ای در خط فرمان برای کنترل سطح بهینه‌سازی که تابع compile() از آن استفاده می‌کند، وجود ندارد، زیرا خود مفسر پایتون از قبل این گزینه را فراهم می‌کند: python -O -m compileall.

به‌طور مشابه، تابع compile() تنظیم sys.pycache_prefix را رعایت می‌کند. نهانگاه بایت‌کد تولیدشده تنها در صورتی مفید خواهد بود که compile() با همان sys.pycache_prefix (در صورت وجود) که در ران‌تایم استفاده خواهد شد، اجرا شود.

توابع عمومی

compileall.compile_dir(dir, maxlevels=sys.getrecursionlimit(), ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)

به‌صورت بازگشتی درخت پوشه‌ای را که با dir نام‌گذاری شده است می‌پیماید و در طول مسیر، همه‌ی پرونده‌های .py را کامپایل می‌کند. اگر همه‌ی پرونده‌ها با موفقیت کامپایل شده باشند، یک مقدار درست و در غیر این صورت یک مقدار نادرست برمی‌گرداند.

پارامتر maxlevels برای محدود کردن عمق بازگشت استفاده می‌شود؛ مقدار پیش‌فرض آن sys.getrecursionlimit() است.

اگر ddir داده شود، این مقدار به ابتدای مسیر هر پرونده‌ای که کامپایل می‌شود افزوده می‌شود تا در ردگیری‌های پشته در زمان کامپایل استفاده شود، و همچنین به‌صورت کامپایل‌شده در پرونده بایت‌کد نیز قرار می‌گیرد؛ در آنجا این مقدار در ردگیری‌های پشته و سایر پیام‌ها در مواردی به کار خواهد رفت که پرونده منبع در زمان اجرای پرونده بایت‌کد وجود ندارد.

اگر force مقدار true داشته باشد، ماژول‌ها دوباره کامپایل می‌شوند، حتی اگر برچسب‌های زمانی به‌روز باشند.

اگر rx داده شود، متد search آن روی مسیر کامل هر پرونده در نظر گرفته‌شده برای کامپایل فراخوانی می‌شود، و اگر مقدار درستی برگرداند، آن پرونده نادیده گرفته می‌شود. این می‌تواند برای مستثنی کردن پرونده‌هایی که با یک عبارت باقاعده مطابقت دارند، به کار رود؛ عبارت باقاعده‌ای که به‌صورت یک شیء re.Pattern داده شده است.

اگر quiet برابر False یا 0 (پیش‌فرض) باشد، نام پرونده‌ها و سایر اطلاعات به خروجی استاندارد چاپ می‌شوند. اگر روی 1 تنظیم شود، فقط خطاها چاپ می‌شوند. اگر روی 2 تنظیم شود، تمام خروجی‌ها سرکوب می‌شوند.

اگر legacy درست باشد، پرونده‌های بایت‌کد در مکان‌ها و با نام‌های قدیمی خود نوشته می‌شوند، که ممکن است باعث رونویسی پرونده‌های بایت‌کد ایجادشده توسط نسخه‌ای دیگر از پایتون شود. پیش‌فرض این است که پرونده‌ها در مکان‌ها و با نام‌های PEP 3147 نوشته شوند، که امکان وجود همزمان پرونده‌های بایت‌کد چندین نسخه از پایتون را فراهم می‌کند.

optimize سطح بهینه‌سازی برای کامپایلر را مشخص می‌کند. این پارامتر به تابع توکار compile() ارسال می‌شود. همچنین دنباله‌ای از سطح‌های بهینه‌سازی را می‌پذیرد که به کامپایل‌های متعدد یک پرونده .py در یک فراخوانی منجر می‌شود.

آرگومان workers مشخص می‌کند که چند کارگر برای کامپایل موازی پرونده‌ها استفاده می‌شوند. پیش‌فرض این است که از چند کارگر استفاده نشود. اگر سکو نتواند از چند کارگر استفاده کند و آرگومان workers داده شده باشد، کامپایل متوالی به‌عنوان حالت جایگزین استفاده خواهد شد. اگر workers برابر ۰ باشد، تعداد هسته‌های سیستم استفاده می‌شود. اگر workers کوچک‌تر از 0 باشد، یک ValueError پرتاب خواهد شد.

invalidation_mode، که باید یکی از اعضای enum py_compile.PycInvalidationMode باشد، نحوه‌ی بی‌اعتبارشدن پرونده‌های pyc تولیدشده در ران‌تایم را کنترل می‌کند.

آرگومان‌های stripdir، prependdir و limit_sl_dest متناظر با گزینه‌های -s، -p و -e هستند که در بالا توضیح داده شده‌اند. می‌توان آن‌ها را به‌صورت str یا os.PathLike مشخص کرد.

اگر hardlink_dupes برابر true باشد و دو پرونده .pyc با سطح بهینه‌سازی متفاوت محتوای یکسانی داشته باشند، برای ادغام پرونده‌های تکراری از پیوندهای سخت (hard links) استفاده می‌شود.

تغییر یافته در نسخه‌ی 3.2: پارامترهای legacy و optimize افزوده شدند.

تغییر یافته در نسخه‌ی 3.5: پارامتر workers افزوده شد.

تغییر یافته در نسخه‌ی 3.5: پارامتر quiet به یک مقدار چندسطحی تغییر کرده است.

تغییر یافته در نسخه‌ی 3.5: پارامتر legacy فقط پرونده‌های .pyc را می‌نویسد، نه پرونده‌های .pyo را، صرف‌نظر از اینکه مقدار optimize چه باشد.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

تغییر یافته در نسخه‌ی 3.7: پارامتر invalidation_mode افزوده شد.

تغییر یافته در نسخه‌ی 3.7.2: مقدار پیش‌فرض پارامتر invalidation_mode به None به‌روزرسانی شده است.

تغییر یافته در نسخه‌ی 3.8: تنظیم workers روی ۰ اکنون تعداد بهینه هسته‌ها را انتخاب می‌کند.

تغییر یافته در نسخه‌ی 3.9: آرگومان‌های stripdir، prependdir، limit_sl_dest و hardlink_dupes افزوده شدند. مقدار پیش‌فرض maxlevels از 10 به sys.getrecursionlimit() تغییر کرد

compileall.compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)

پرونده را با مسیر fullname کامپایل می‌کند. اگر پرونده با موفقیت کامپایل شد، مقدار درست و در غیر این صورت مقدار نادرست برمی‌گرداند.

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

اگر rx داده شود، متد search آن نام کامل مسیر پرونده‌ای را که در حال کامپایل شدن است دریافت می‌کند، و اگر یک مقدار درست برگرداند، آن پرونده کامپایل نمی‌شود و True برگردانده می‌شود. می‌توان از این برای مستثنی کردن پرونده‌هایی که با یک عبارت باقاعده مطابقت دارند استفاده کرد؛ عبارت باقاعدهی که به‌صورت یک شیء re.Pattern داده شده است.

اگر quiet برابر False یا 0 (پیش‌فرض) باشد، نام پرونده‌ها و سایر اطلاعات به خروجی استاندارد چاپ می‌شوند. اگر روی 1 تنظیم شود، فقط خطاها چاپ می‌شوند. اگر روی 2 تنظیم شود، تمام خروجی‌ها سرکوب می‌شوند.

اگر legacy درست باشد، پرونده‌های بایت‌کد در مکان‌ها و با نام‌های قدیمی خود نوشته می‌شوند، که ممکن است باعث رونویسی پرونده‌های بایت‌کد ایجادشده توسط نسخه‌ای دیگر از پایتون شود. پیش‌فرض این است که پرونده‌ها در مکان‌ها و با نام‌های PEP 3147 نوشته شوند، که امکان وجود همزمان پرونده‌های بایت‌کد چندین نسخه از پایتون را فراهم می‌کند.

optimize سطح بهینه‌سازی برای کامپایلر را مشخص می‌کند. این پارامتر به تابع توکار compile() ارسال می‌شود. همچنین دنباله‌ای از سطح‌های بهینه‌سازی را می‌پذیرد که به کامپایل‌های متعدد یک پرونده .py در یک فراخوانی منجر می‌شود.

invalidation_mode، که باید یکی از اعضای enum py_compile.PycInvalidationMode باشد، نحوه‌ی بی‌اعتبارشدن پرونده‌های pyc تولیدشده در ران‌تایم را کنترل می‌کند.

آرگومان‌های stripdir، prependdir و limit_sl_dest متناظر با گزینه‌های -s، -p و -e هستند که در بالا توضیح داده شده‌اند. می‌توان آن‌ها را به‌صورت str یا os.PathLike مشخص کرد.

اگر hardlink_dupes برابر true باشد و دو پرونده .pyc با سطح بهینه‌سازی متفاوت محتوای یکسانی داشته باشند، برای ادغام پرونده‌های تکراری از پیوندهای سخت (hard links) استفاده می‌شود.

اضافه شده در نسخه‌ی 3.2.

تغییر یافته در نسخه‌ی 3.5: پارامتر quiet به یک مقدار چندسطحی تغییر کرده است.

تغییر یافته در نسخه‌ی 3.5: پارامتر legacy فقط پرونده‌های .pyc را می‌نویسد، نه پرونده‌های .pyo را، صرف‌نظر از اینکه مقدار optimize چه باشد.

تغییر یافته در نسخه‌ی 3.7: پارامتر invalidation_mode افزوده شد.

تغییر یافته در نسخه‌ی 3.7.2: مقدار پیش‌فرض پارامتر invalidation_mode به None به‌روزرسانی شده است.

تغییر یافته در نسخه‌ی 3.9: آرگومان‌های stripdir، prependdir، limit_sl_dest و hardlink_dupes افزوده شدند.

compileall.compile_path(skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1, invalidation_mode=None)

تمام پرونده‌های .py یافت‌شده در sys.path را بایت‌کامپایل می‌کند. اگر همه‌ی پرونده‌ها با موفقیت بایت‌کامپایل شده باشند، مقدار درست برمی‌گرداند و در غیر این صورت مقدار نادرست.

اگر skip_curdir درست باشد (پیش‌فرض)، پوشه‌ی جاری در جستجو لحاظ نمی‌شود. همه‌ی پارامترهای دیگر به تابع compile_dir() ارسال می‌شوند. توجه داشته باشید که برخلاف سایر توابع کامپایل، مقدار پیش‌فرض maxlevels برابر 0 است.

تغییر یافته در نسخه‌ی 3.2: پارامترهای legacy و optimize افزوده شدند.

تغییر یافته در نسخه‌ی 3.5: پارامتر quiet به یک مقدار چندسطحی تغییر کرده است.

تغییر یافته در نسخه‌ی 3.5: پارامتر legacy فقط پرونده‌های .pyc را می‌نویسد، نه پرونده‌های .pyo را، صرف‌نظر از اینکه مقدار optimize چه باشد.

تغییر یافته در نسخه‌ی 3.7: پارامتر invalidation_mode افزوده شد.

تغییر یافته در نسخه‌ی 3.7.2: مقدار پیش‌فرض پارامتر invalidation_mode به None به‌روزرسانی شده است.

برای وادار کردن به کامپایل مجدد تمام پرونده‌های .py در زیرپوشه‌ی Lib/ و تمام زیرپوشه‌های آن:

import compileall

compileall.compile_dir('Lib/', force=True)

# Perform same compilation, excluding files in .svn directories.
import re
compileall.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), force=True)

# pathlib.Path objects can also be used.
import pathlib
compileall.compile_dir(pathlib.Path('Lib/'), force=True)

همچنین ملاحظه نمائید

ماژول py_compile

یک پرونده منبع را به بایت‌کد کامپایل کنید.