.\" Man page generated from reStructuredText
.\" by the Docutils 0.23 manpage writer.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "PY2LCOV" "1" "2026-07-07" "2.5" "LCOV"
.SH "نام (NAME)"
py2lcov \- تبدیل داده‌های Coverage.py پایتون به قالب lcov
.INDENT 0.0
.TP
.B بخش راهنما
1
.TP
.B گروه راهنما
LCOV Tools
.UNINDENT
.SH "نام (NAME)"
.INDENT 0.0
.TP
.B py2lcov
تبدیل داده‌های \fBCoverage.py\fP پایتون به قالب lcov
.UNINDENT
.SH "خلاصه دستور (SYNOPSIS)"
.INDENT 0.0
.INDENT 3.5
.sp
.EX
py2lcov [\-\-output mydata.info] [\-\-test\-name name] [options] coverage.dat+
.EE
.UNINDENT
.UNINDENT
.SH "توضیحات (DESCRIPTION)"
.sp
ابزار \fBpy2lcov\fP داده‌های پوشش پایتون را در یک یا چند فایل داده‌های پوشش (تولیدشده توسط ماژول \fBCoverage.py\fP) پیمایش کرده و آن‌ها را به قالب \fB\&.info\fP ابزار LCOV تبدیل می‌کند.
.sp
توجه داشته باشید که آرگومان \fB\-\-no\-functions\fP ممکن است در صورتی که یک پایگاه‌داده پوشش \fBno\-functions\fP با پایگاه‌داده‌ای حاوی داده‌های مشتق‌شده از توابع ادغام شود، به داده‌های پوشش با ناسازگاری‌های نامحسوس منجر گردد. دلیل این امر آن است که خط \fBdef myFunc(...)\fP مقدار شمارش اجرای ۱ را دریافت خواهد کرد (مفسر پایتون اجرای \fBdef\fP را هنگام تفسیر خط، یعنی زمان تعریف تابع، لحاظ می‌کند). در صورتی که تابع در آزمون‌های شما اجرا نشود، این حالت موجب بروز خطای \fBinconsistent\fP خواهد شد؛ زیرا تابع (مشتق‌شده) دارای شمارش اجرای صفر است اما خط اول تابع مقداری غیرصفر دارد.
.sp
\fBبهترین شیوه\fP: یا همواره \fB\-\-no\-functions\fP را مشخص کنید یا هرگز \fB\-\-no\-functions\fP را به کار نبرید\&.
.sp
ابزار \fBpy2lcov\fP از \fBCoverage.py\fP برای استخراج داده‌های پوشش استفاده می‌کند. نام فایل اجرایی \fBCoverage.py\fP ممکن است در پلتفرم شما متفاوت باشد. به‌طور پیش‌فرض، \fBpy2lcov\fP از \fBcoverage\fP استفاده می‌کند (که انتظار می‌رود در PATH شما موجود باشد). شما می‌توانید از طریق متغیر محیطی \fBCOVERAGE_COMMAND\fP یا گزینه خط فرمان \fB\-\-cmd\fP از فایل اجرایی دیگری استفاده کنید.
.sp
ابزار \fBpy2lcov\fP تمام مجموعه ویژگی‌های LCOV (مانند فیلترسازی، جایگزینی‌ها و غیره) را پیاده‌سازی نمی‌کند. ابتدا فایل با قالب ترجمه‌شده LCOV را تولید کرده و سپس داده‌ها را دوباره در \fBlcov\fP بخوانید تا بتوانید از این ویژگی‌ها بهره ببرید.
.sp
\fBمحدودیت‌های پوشش شاخه (Branch Coverage)\fP
.sp
توجه داشته باشید که قالب داده‌های پوشش XML اطلاعات کافی برای استنتاج دقیق این که کدام عبارت‌های شاخه طی شده‌اند یا نشده‌اند را در خود ندارد. این قالب فقط تعداد کل عبارت‌های شاخه مرتبط با یک خط مشخص و تعداد موارد طی‌شده از بین آن‌ها را گزارش می‌کند. هیچ راهی برای آگاهی از این که دقیقاً کدام موارد بوده‌اند وجود ندارد (مگر احتمالاً از طریق بررسی کدهای پیرامون یا درک نحوه پیاده‌سازی برنامه).
.sp
این موضوع دست‌کم از ۲ جهت مشکل‌ساز است:
.INDENT 0.0
.IP \(bu 2
استفاده از نتیجه برای بهبود مجموعه آزمون‌های رگرسیون سرراست نیست، زیرا شما واقعاً نمی‌دانید چه مواردی آزموده شده یا نشده‌اند.
.IP \(bu 2
ادغام داده‌های پوشش با مشکل روبه‌رو می‌شود. برای نمونه: دو فایل XML مربوط به آزمون‌ها دارید که هر کدام ۴ شاخه از ۸ شاخه را در یک خط خاص پوشش داده‌اند. آیا این بدان معناست که ۴ مورد از آن‌ها طی شده است (هر دو آزمون کد یکسانی را اجرا کرده‌اند)، هر ۸ مورد (آزمون‌ها زیرمجموعه‌های مجزایی را اجرا کرده‌اند)، یا عددی بین این دو؟
.UNINDENT
.sp
این پیاده‌سازی فرض می‌کند که در هر مورد آزمون، M شاخه اول مواردی هستند که اجرا شده‌اند و N\-M شاخه باقی‌مانده اجرا نشده‌اند. بنابراین، نتیجه ترکیبی در مثال بالا مدعی پوشش ۴ شاخه از ۸ شاخه خواهد بود. این تعریف در عمل یک حد پایین (lower bound) محسوب می‌شود.
.SH "گزینه‌ها (OPTIONS)"
.INDENT 0.0
.TP
.B \fB\-i\fP, \fB\-\-input\fP \fIfile\fP
\fBمنسوخ‌شده\fP: فایل XML ورودی از \fBcoverage.py\fP را مشخص می‌کند\&.
.TP
.B \fB\-o\fP, \fB\-\-output\fP \fIfile\fP
فایل خروجی \fB\&.info\fP ابزار LCOV را مشخص می‌کند. پیش‌فرض: \fBpy2lcov.info\fP\&.
.TP
.B \fB\-t\fP, \fB\-\-test\-name\fP, \fB\-\-testname\fP \fIname\fP
نام آزمون را برای مدخل \fBTN:\fP در فایل \fB\&.info\fP ابزار LCOV مشخص می‌کند.
.TP
.B \fB\-e\fP, \fB\-\-exclude\fP \fIpatterns\fP
الگوهای فایل‌های مستثنی‌شده را که با کاما از هم جدا شده‌اند مشخص می‌کند.
.TP
.B \fB\-v\fP, \fB\-\-verbose\fP
پیام‌های اشکال‌زدایی را چاپ می‌کند.
.TP
.B \fB\-\-version\-script\fP \fIscript\fP
اسکریپت بازخوانی برای استخراج نسخه.
.TP
.B \fB\-\-checksum\fP
محاسبه چک‌سام خط. به \fBlcov(1) \%<file://\:\:../\:man/\:lcov\:.1\:.html>\fP مراجعه کنید\&.
.TP
.B \fB\-\-no\-functions\fP
نقاط پوشش تابع را استخراج نمی‌کند.
.TP
.B \fB\-\-tabwidth\fP \fIn\fP
اندازه نویسه تب هنگام محاسبه تورفتگی. پیش‌فرض: 8.
.TP
.B \fB\-k\fP, \fB\-\-keep\-going\fP
خطاها را نادیده گرفته و به پردازش ادامه می‌دهد.
.TP
.B \fB\-\-cmd\fP \fIexecutable\fP
فایل اجرایی مورد استفاده برای استخراج داده‌های پوشش پایتون (مانند \fBpython3\-coverage\fP).
پیش‌فرض: \fBcoverage\fP (یا مقدار متغیر محیطی \fBCOVERAGE_COMMAND\fP).
.UNINDENT
.sp
توجه داشته باشید که \fBpy2lcov\fP یک فایل اجرایی مستقل پایتون است؛ از این رو مستقیماً از گزینه‌های استاندارد خط فرمان و تنظیمات RC ابزار LCOV (برای نمونه برای فیلترسازی، گنجاندن یا مستثنی‌کردن فایل‌ها و غیره) پشتیبانی \fIنمی‌کند\fP.
برای استفاده از این گزینه‌ها، باید ابتدا با استفاده از \fBpy2lcov\fP پایگاه‌داده پوشش خود را ثبت کنید و سپس گزینه‌های دلخواه خود را از طریق \fBlcov \-a pycov.info <options> ...\fP اعمال نمایید\&. برای جزئیات به \fBlcov(1) \%<file://\:\:../\:man/\:lcov\:.1\:.html>\fP مراجعه فرمایید.
.SH "مثال‌ها (EXAMPLES)"
.sp
گردش کار پایه:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ export PYCOV_DATA=path/to/pydata

# برای نسخه‌های \(aqcoverage\(aq ۶.۶.۱ و بالاتر (با پشتیبانی از \(dq\-\-data\-file\(dq):
$ coverage run \-\-data\-file=${PYCOV_DATA} \-\-append \-\-branch \e
    /path/to/myPythonScript.py args_to_my_python_script

# برای نسخه‌های قدیمی‌تر بدون پشتیبانی از \(dq\-\-data\-file\(dq:
$ COVERAGE_FILE=${PYCOV_DATA} coverage run \-\-append \-\-branch \e
    /path/to/myPythonScript.py args_to_my_python_script

# تبدیل به قالب LCOV:
$ py2lcov \-o pydata.info ${PYCOV_DATA}

# اعمال فیلترسازی:
$ lcov \-a pydata.info \-o filtered.info \-\-filter branch,blank

# تولید گزارش HTML:
$ genhtml \-o html_report pydata.info

# تولید گزارش فیلترشده:
$ genhtml \-o html_filtered filtered.info

# استفاده از پوشش دیفرانسیلی برای مشاهده اثر فیلترسازی:
$ genhtml \-o html_differential \-\-baseline\-file mydata.info filtered.info
.EE
.UNINDENT
.UNINDENT
.sp
حالت ورودی منسوخ‌شده XML:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# ابتدا تبدیل داده‌های پوشش پایتون به XML:
$ coverage xml \-\-data\-file=${PYCOV_DATA} \-o pydata.xml

# سپس تبدیل XML به قالب LCOV:
$ py2lcov \-i pydata.xml \-o pydata.info \-\-version\-script myCovScript
.EE
.UNINDENT
.UNINDENT
.SH "محیط (ENVIRONMENT)"
.INDENT 0.0
.TP
.B \fBCOVERAGE_COMMAND\fP
جایگزین کردن فایل اجرایی پیش‌فرض \fBcoverage\fP که برای استخراج داده‌های پوشش پایتون به کار می‌رود.
.TP
.B \fBCOVERAGE_FILE\fP
فایل ورودی پیش‌فرض در صورتی که هیچ فایلی در خط فرمان مشخص نشده باشد.
.UNINDENT
.SH "نویسندگان (AUTHORS)"
.sp
Henry Cox <\%<henry\:.cox@\:mediatek\:.com>>
.SH "همچنین ببینید (SEE ALSO)"
.sp
\fBlcov(1) \%<file://\:\:../\:man/\:lcov\:.1\:.html>\fP, \fBgenhtml(1) \%<file://\:\:../\:man/\:genhtml\:.1\:.html>\fP, \fBgeninfo(1) \%<file://\:\:../\:man/\:geninfo\:.1\:.html>\fP
.INDENT 0.0
.IP \(bu 2
مستندات \fBCoverage.py\fP: \%<https://\:coverage\:.readthedocs\:.io>
.UNINDENT
.SH "کپی‌رایت و تکثیر (COPYRIGHT)"
2024-2026, LCOV Project
.\" End of generated man page.