py_compile --- کامپایل پروندههای منبع پایتون¶
کد منبع: Lib/py_compile.py
ماژول py_compile تابعی برای تولید یک پرونده بایتکد از یک پرونده منبع و تابع دیگری را ارائه میکند که هنگام فراخوانی پرونده منبع ماژول بهعنوان یک اسکریپت استفاده میشود.
اگرچه اغلب به آن نیاز نیست، این تابع میتواند هنگام نصب ماژولها برای استفاده مشترک مفید باشد، بهویژه اگر برخی از کاربران اجازه نوشتن پروندههای نهانگاه بایتکد (byte-code) را در پوشه حاوی کد منبع نداشته باشند.
- exception py_compile.PyCompileError¶
استثنایی که هنگام بروز خطا در تلاش برای کامپایل پرونده پرتاب میشود.
- py_compile.compile(file, cfile=None, dfile=None, doraise=False, optimize=-1, invalidation_mode=PycInvalidationMode.TIMESTAMP, quiet=0)¶
یک پرونده منبع را به بایتکد کامپایل میکند و پرونده نهانگاه بایتکد را مینویسد. کد منبع از پروندهای با نام file بارگذاری میشود. بایتکد در cfile نوشته میشود، که بهطور پیشفرض مسیر PEP 3147/PEP 488 است و به
.pycختم میشود. برای مثال، اگر file برابر/foo/bar/baz.pyباشد، cfile برای پایتون 3.2 بهطور پیشفرض برابر/foo/bar/__pycache__/baz.cpython-32.pycخواهد بود. اگر dfile مشخص شده باشد، بهجای file بهعنوان نام پرونده منبعی استفاده میشود که سطرهای منبع برای نمایش در ردگیریهای استثنا از آن گرفته میشوند. اگر doraise درست باشد، هنگامی که در حین کامپایل file با خطایی مواجه شود، یکPyCompileErrorپرتاب میشود. اگر doraise نادرست باشد (پیشفرض)، یک رشته خطا درsys.stderrنوشته میشود، اما هیچ استثنایی پرتاب نمیشود. این تابع مسیر پرونده کامپایلشده به بایتکد را برمیگرداند، یعنی هر مقداری که برای cfile استفاده شده باشد.آرگومانهای doraise و quiet تعیین میکنند که خطاها هنگام کامپایل پرونده چگونه مدیریت میشوند. اگر quiet برابر ۰ یا ۱ باشد و doraise نادرست باشد، رفتار پیشفرض فعال میشود: یک رشتهی خطا در
sys.stderrنوشته میشود و تابع بهجای یک مسیر،Noneرا برمیگرداند. اگر doraise درست باشد، بهجای آن یکPyCompileErrorپرتاب میشود. با این حال اگر quiet برابر ۲ باشد، هیچ پیامی نوشته نمیشود و doraise هیچ تأثیری ندارد.اگر مسیری که cfile به آن تبدیل میشود (چه بهصورت صریح مشخصشده باشد و چه محاسبهشده باشد) یک پیوند نمادین یا پرونده غیرعادی باشد،
FileExistsErrorپرتاب خواهد شد. این بهعنوان هشداری است مبنی بر اینکه ایمپورت، در صورتی که اجازه داشته باشد پروندههای بایتکامپایلشده (byte-compiled) را در آن مسیرها بنویسد، آن مسیرها را به پروندههای عادی تبدیل خواهد کرد. این یک اثر جانبی از این است که ایمپورت برای قرار دادن پرونده نهایی بایتکامپایلشده در محل خود از تغییر نام پرونده استفاده میکند تا از مشکلات نوشتن همزمان پروندهها جلوگیری کند.optimize سطح بهینهسازی را کنترل میکند و به تابع توکار
compile()ارسال میشود. مقدار پیشفرض-1سطح بهینهسازی مفسر جاری را انتخاب میکند.invalidation_mode باید عضوی از شمارش (enum)
PycInvalidationModeباشد و نحوهی باطل شدن نهانگاه بایتکد تولیدشده در رانتایم را کنترل میکند. اگر متغیر محیطیSOURCE_DATE_EPOCHتنظیم شده باشد، مقدار پیشفرضPycInvalidationMode.CHECKED_HASHاست، در غیر این صورت مقدار پیشفرضPycInvalidationMode.TIMESTAMPاست.تغییر یافته در نسخهی 3.2: مقدار پیشفرض cfile تغییر کرد تا با PEP 3147 سازگار باشد. مقدار پیشفرض قبلی file +
'c'بود (اگر بهینهسازی فعال بود،'o'). همچنین پارامتر optimize افزوده شد.تغییر یافته در نسخهی 3.4: کد برای استفاده از
importlibجهت نوشتن پرونده نهانگاه بایتکد تغییر کرد. این بدان معناست که رفتار ایجاد/نوشتن پرونده اکنون با آنچهimportlibانجام میدهد مطابقت دارد، برای مثال مجوزها، رفتار نوشتن و جابهجایی، و غیره. همچنین این نکته افزوده شد که اگر cfile یک پیوند نمادین یا پرونده غیرمعمول باشد،FileExistsErrorپرتاب میشود.تغییر یافته در نسخهی 3.7: پارامتر invalidation_mode همانطور که در PEP 552 مشخص شده است، افزوده شد. اگر متغیر محیطی
SOURCE_DATE_EPOCHتنظیم شده باشد، invalidation_mode بهصورت اجباری رویPycInvalidationMode.CHECKED_HASHتنظیم خواهد شد.تغییر یافته در نسخهی 3.7.2: متغیر محیطی
SOURCE_DATE_EPOCHدیگر مقدار آرگومان invalidation_mode را بازنویسی نمیکند و در عوض مقدار پیشفرض آن را تعیین میکند.تغییر یافته در نسخهی 3.8: پارامتر quiet افزوده شد.
- class py_compile.PycInvalidationMode¶
شمارشی از روشهای ممکنی که مفسر میتواند برای تعیین اینکه آیا یک پرونده بایتکد با یک پرونده منبع بهروز است، از آنها استفاده کند. پرونده
.pycحالت نامعتبرسازی موردنظر را در سرآیند خود نشان میدهد. برای اطلاعات بیشتر دربارهی نحوهی نامعتبرسازی پروندههای.pycتوسط پایتون در رانتایم، بیاعتبارسازی بایتکد نهانشده را ببینید.اضافه شده در نسخهی 3.7.
- TIMESTAMP¶
پرونده
.pycشامل برچسب زمانی و اندازهی پرونده منبع است که پایتون آنها را در رانتایم با فرادادهی پرونده منبع مقایسه میکند تا تعیین کند که آیا پرونده.pycنیاز به بازتولید دارد یا خیر.
- CHECKED_HASH¶
پرونده
.pycشامل یک هش از محتوای پرونده منبع است که پایتون آن را در رانتایم با منبع مقایسه میکند تا تعیین کند که آیا پرونده.pycنیاز به بازتولید دارد یا خیر.
- UNCHECKED_HASH¶
مانند
CHECKED_HASH، پرونده.pycشامل هش محتوای پرونده منبع است. با این حال، پایتون در رانتایم فرض میکند که پرونده.pycبهروز است و پرونده.pycرا بههیچوجه در برابر پرونده منبع اعتبارسنجی نمیکند.این گزینه زمانی مفید است که پروندههای
.pycsتوسط سیستمی خارج از پایتون، مانند یک سیستم ساخت، بهروز نگه داشته شوند.
رابط خط فرمان¶
این ماژول را میتوان بهعنوان یک اسکریپت برای کامپایل چند پرونده منبع فراخوانی کرد. پروندههای نامبردهشده در filenames کامپایل میشوند و بایتکد حاصل بهروش معمول در نهانگاه ذخیره میشود. این برنامه یک ساختار پوشهای را برای یافتن پروندههای منبع جستجو نمیکند؛ فقط پروندههایی را کامپایل میکند که بهصراحت نام برده شدهاند. وضعیت خروجی در صورتی غیرصفر است که یکی از پروندهها قابل کامپایل نباشد.
- <file> ... <fileN>¶
- -¶
آرگومانهای جایگاهی، پروندههایی هستند که باید کامپایل شوند. اگر
-تنها پارامتر باشد، فهرست پروندهها از ورودی استاندارد گرفته میشود.
- -q, --quiet¶
خروجی خطاها را سرکوب میکند.
تغییر یافته در نسخهی 3.2: پشتیبانی از - اضافه شد.
تغییر یافته در نسخهی 3.10: پشتیبانی از -q افزوده شد.
همچنین ملاحظه نمائید
- ماژول
compileall ابزارهایی برای کامپایل کردن تمام پروندههای منبع پایتون در یک درخت پوشهها.