# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2001 Python Software Foundation
# This file is distributed under the same license as the Python package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
# Translators:
# Danial Behzadi <dani.behzi@ubuntu.com>, 2025
# Rafael Fontenelle <rffontenelle@gmail.com>, 2025
# Revisto <theRevisto@gmail.com>, 2025
# Sepehr Rasouli <sepehrrasouli06@gmail.com>, 2026
#
msgid ""
msgstr ""
"Project-Id-Version: Python 3.14\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2026-10-01 14:41+0330\n"
"PO-Revision-Date: 2026-09-15 10:50+0330\n"
"Last-Translator: Sepehr Rasouli <sepehrrasouli06@gmail.com>, 2026\n"
"Language-Team: Persian (https://github.com/python/python-docs-fa/)\n"
"Language: fa\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n > 1);\n"
"X-Generator: Poedit 3.6\n"

msgid "Argparse Tutorial"
msgstr "آموزش Argparse"

msgid "This tutorial is intended to be a gentle introduction to :mod:`argparse`, the recommended command-line parsing module in the Python standard library."
msgstr "این آموزش در نظر دارد مقدمه‌ای ملایم به :mod:`argparse`، ماژول توصیه‌شده برای تجزیه خط فرمان در کتابخانه استاندارد پایتون، باشد."

msgid "The standard library includes two other libraries directly related to command-line parameter processing: the lower level :mod:`optparse` module (which may require more code to configure for a given application, but also allows an application to request behaviors that ``argparse`` doesn't support), and the very low level :mod:`getopt` (which specifically serves as an equivalent to the :c:func:`!getopt` family of functions available to C programmers). While neither of those modules is covered directly in this guide, many of the core concepts in ``argparse`` first originated in ``optparse``, so some aspects of this tutorial will also be relevant to ``optparse`` users."
msgstr "کتابخانه استاندارد شامل دو کتابخانه دیگر است که مستقیماً به پردازش پارامترهای خط فرمان مرتبط هستند: ماژول :mod:`optparse` در سطح پایین‌تر (که ممکن است برای پیکربندی یک برنامه مشخص به کد بیشتری نیاز داشته باشد، اما همچنین به برنامه اجازه می‌دهد رفتارهایی را درخواست کند که ``argparse`` از آن‌ها پشتیبانی نمی‌کند)، و :mod:`getopt` بسیار سطح پایین (که مشخصاً به‌عنوان معادلی برای خانواده توابع :c:func:`!getopt` در دسترس برنامه‌نویسان C عمل می‌کند). اگرچه هیچ‌کدام از این ماژول‌ها مستقیماً در این راهنما پوشش داده نمی‌شوند، بسیاری از مفاهیم اصلی ``argparse`` ابتدا در ``optparse`` پدید آمدند، بنابراین برخی از جنبه‌های این آموزش برای کاربران ``optparse`` نیز مرتبط خواهند بود."

msgid "Concepts"
msgstr "مفاهیم"

msgid "Let's show the sort of functionality that we are going to explore in this introductory tutorial by making use of the :command:`ls` command:"
msgstr "بیایید با استفاده از دستور :command:`ls`، نوع قابلیت‌هایی را که در این آموزش مقدماتی بررسی خواهیم کرد، نشان دهیم:"

msgid ""
"$ ls\n"
"cpython  devguide  prog.py  pypy  rm-unused-function.patch\n"
"$ ls pypy\n"
"ctypes_configure  demo  dotviewer  include  lib_pypy  lib-python ...\n"
"$ ls -l\n"
"total 20\n"
"drwxr-xr-x 19 wena wena 4096 Feb 18 18:51 cpython\n"
"drwxr-xr-x  4 wena wena 4096 Feb  8 12:04 devguide\n"
"-rwxr-xr-x  1 wena wena  535 Feb 19 00:05 prog.py\n"
"drwxr-xr-x 14 wena wena 4096 Feb  7 00:59 pypy\n"
"-rw-r--r--  1 wena wena  741 Feb 18 01:01 rm-unused-function.patch\n"
"$ ls --help\n"
"Usage: ls [OPTION]... [FILE]...\n"
"List information about the FILEs (the current directory by default).\n"
"Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n"
"..."
msgstr ""
"$ ls\n"
"cpython  devguide  prog.py  pypy  rm-unused-function.patch\n"
"$ ls pypy\n"
"ctypes_configure  demo  dotviewer  include  lib_pypy  lib-python ...\n"
"$ ls -l\n"
"total 20\n"
"drwxr-xr-x 19 wena wena 4096 Feb 18 18:51 cpython\n"
"drwxr-xr-x  4 wena wena 4096 Feb  8 12:04 devguide\n"
"-rwxr-xr-x  1 wena wena  535 Feb 19 00:05 prog.py\n"
"drwxr-xr-x 14 wena wena 4096 Feb  7 00:59 pypy\n"
"-rw-r--r--  1 wena wena  741 Feb 18 01:01 rm-unused-function.patch\n"
"$ ls --help\n"
"Usage: ls [OPTION]... [FILE]...\n"
"List information about the FILEs (the current directory by default).\n"
"Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n"
"..."

msgid "A few concepts we can learn from the four commands:"
msgstr "چند مفهوم که می‌توانیم از ۴ دستور بیاموزیم:"

msgid "The :command:`ls` command is useful when run without any options at all. It defaults to displaying the contents of the current directory."
msgstr "فرمان :command:`ls` زمانی که بدون هیچ گزینه‌ای اجرا شود، مفید است. این فرمان به‌طور پیش‌فرض محتویات پوشه جاری را نمایش می‌دهد."

msgid "If we want beyond what it provides by default, we tell it a bit more. In this case, we want it to display a different directory, ``pypy``. What we did is specify what is known as a positional argument. It's named so because the program should know what to do with the value, solely based on where it appears on the command line. This concept is more relevant to a command like :command:`cp`, whose most basic usage is ``cp SRC DEST``. The first position is *what you want copied,* and the second position is *where you want it copied to*."
msgstr "اگر بخواهیم فراتر از آنچه به‌طور پیش‌فرض فراهم می‌کند، کمی بیشتر به آن می‌گوییم. در این حالت، می‌خواهیم پوشه‌ای متفاوت، یعنی ``pypy`` را نمایش دهد. کاری که انجام دادیم مشخص کردن چیزی است که به‌عنوان آرگومان جایگاهی شناخته می‌شود. این‌گونه نام‌گذاری شده است زیرا برنامه باید صرفاً بر اساس محل قرارگیری آن در خط فرمان بداند با مقدار چه کاری انجام دهد. این مفهوم بیشتر به دستوری مانند :command:`cp` مربوط است، که ابتدایی‌ترین کاربرد آن ``cp SRC DEST`` است. جایگاه اول *چیزی است که می‌خواهید کپی شود،* و جایگاه دوم *جایی است که می‌خواهید به آن کپی شود*."

msgid "Now, say we want to change behaviour of the program. In our example, we display more info for each file instead of just showing the file names. The ``-l`` in that case is known as an optional argument."
msgstr "حال، فرض کنید می‌خواهیم رفتار برنامه را تغییر دهیم. در مثال خود، به‌جای نمایش فقط نام پرونده‌ها، اطلاعات بیشتری برای هر پرونده نمایش می‌دهیم. در این حالت، ``-l`` به‌عنوان یک آرگومان اختیاری شناخته می‌شود."

msgid "That's a snippet of the help text. It's very useful in that you can come across a program you have never used before, and can figure out how it works simply by reading its help text."
msgstr "این قطعه‌ای از متن راهنما است. این بسیار مفید است، زیرا می‌توانید با برنامه‌ای مواجه شوید که هرگز پیش‌تر از آن استفاده نکرده‌اید و صرفاً با خواندن متن راهنمای آن بفهمید که چگونه کار می‌کند."

msgid "The basics"
msgstr "مبانی"

msgid "Let us start with a very simple example which does (almost) nothing::"
msgstr "بیایید با مثال بسیار ساده‌ای شروع کنیم که (تقریباً) هیچ کاری انجام نمی‌دهد::"

msgid ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.parse_args()"
msgstr ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.parse_args()"

msgid "Following is a result of running the code:"
msgstr "نتیجه‌ی اجرای کد به شرح زیر است:"

msgid ""
"$ python prog.py\n"
"$ python prog.py --help\n"
"usage: prog.py [-h]\n"
"\n"
"options:\n"
"  -h, --help  show this help message and exit\n"
"$ python prog.py --verbose\n"
"usage: prog.py [-h]\n"
"prog.py: error: unrecognized arguments: --verbose\n"
"$ python prog.py foo\n"
"usage: prog.py [-h]\n"
"prog.py: error: unrecognized arguments: foo"
msgstr ""
"$ python prog.py\n"
"$ python prog.py --help\n"
"usage: prog.py [-h]\n"
"\n"
"options:\n"
"  -h, --help  show this help message and exit\n"
"$ python prog.py --verbose\n"
"usage: prog.py [-h]\n"
"prog.py: error: unrecognized arguments: --verbose\n"
"$ python prog.py foo\n"
"usage: prog.py [-h]\n"
"prog.py: error: unrecognized arguments: foo"

msgid "Here is what is happening:"
msgstr "آنچه اتفاق می‌افتد به این صورت است:"

msgid "Running the script without any options results in nothing displayed to stdout. Not so useful."
msgstr "اجرای اسکریپت بدون هیچ گزینه‌ای باعث می‌شود چیزی در stdout نمایش داده نشود. چندان مفید نیست."

msgid "The second one starts to display the usefulness of the :mod:`argparse` module. We have done almost nothing, but already we get a nice help message."
msgstr "دومی شروع به نمایش سودمندی ماژول :mod:`argparse` می‌کند. ما تقریباً هیچ کاری انجام نداده‌ایم، اما از همین حالا یک پیام راهنمای مناسب دریافت می‌کنیم."

msgid "The ``--help`` option, which can also be shortened to ``-h``, is the only option we get for free (i.e. no need to specify it). Specifying anything else results in an error. But even then, we do get a useful usage message, also for free."
msgstr "گزینه‌ی ``--help``، که می‌توان آن را به ``-h`` نیز مخفف کرد، تنها گزینه‌ای است که به‌رایگان در اختیار داریم (یعنی نیازی به مشخص کردن آن نیست). مشخص کردن هر چیز دیگری منجر به خطا می‌شود. اما حتی در آن حالت نیز یک پیام کاربرد مفید، به‌رایگان دریافت می‌کنیم."

msgid "Introducing Positional arguments"
msgstr "معرفی آرگومان‌های جایگاهی"

msgid "An example::"
msgstr "یک مثال::"

msgid ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"echo\")\n"
"args = parser.parse_args()\n"
"print(args.echo)"
msgstr ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"echo\")\n"
"args = parser.parse_args()\n"
"print(args.echo)"

msgid "And running the code:"
msgstr "و اجرای کد:"

msgid ""
"$ python prog.py\n"
"usage: prog.py [-h] echo\n"
"prog.py: error: the following arguments are required: echo\n"
"$ python prog.py --help\n"
"usage: prog.py [-h] echo\n"
"\n"
"positional arguments:\n"
"  echo\n"
"\n"
"options:\n"
"  -h, --help  show this help message and exit\n"
"$ python prog.py foo\n"
"foo"
msgstr ""
"$ python prog.py\n"
"usage: prog.py [-h] echo\n"
"prog.py: error: the following arguments are required: echo\n"
"$ python prog.py --help\n"
"usage: prog.py [-h] echo\n"
"\n"
"positional arguments:\n"
"  echo\n"
"\n"
"options:\n"
"  -h, --help  show this help message and exit\n"
"$ python prog.py foo\n"
"foo"

msgid "Here is what's happening:"
msgstr "آنچه در حال رخ دادن است:"

msgid "We've added the :meth:`~ArgumentParser.add_argument` method, which is what we use to specify which command-line options the program is willing to accept. In this case, I've named it ``echo`` so that it's in line with its function."
msgstr "ما متد :meth:`~ArgumentParser.add_argument` را اضافه کرده‌ایم، که از آن برای مشخص کردن این‌که برنامه مایل به پذیرش کدام گزینه‌های خط فرمان است، استفاده می‌کنیم. در این مورد، من آن را ``echo`` نام‌گذاری کرده‌ام تا با تابع خود هماهنگ باشد."

msgid "Calling our program now requires us to specify an option."
msgstr "اکنون برای فراخوانی برنامه‌ی خود باید یک گزینه را مشخص کنیم."

msgid "The :meth:`~ArgumentParser.parse_args` method actually returns some data from the options specified, in this case, ``echo``."
msgstr "متد :meth:`~ArgumentParser.parse_args` در واقع مقداری داده از گزینه‌های مشخص‌شده برمی‌گرداند، در این حالت، ``echo``."

msgid "The variable is some form of 'magic' that :mod:`argparse` performs for free (i.e. no need to specify which variable that value is stored in). You will also notice that its name matches the string argument given to the method, ``echo``."
msgstr "این متغیر نوعی «جادو» است که :mod:`argparse` بدون نیاز به اقدام اضافه از سوی شما انجام می‌دهد (یعنی نیازی نیست مشخص کنید آن مقدار در کدام متغیر ذخیره می‌شود). همچنین متوجه خواهید شد که نام آن با آرگومان رشته‌ای داده‌شده به متد، ``echo``، مطابقت دارد."

msgid "Note however that, although the help display looks nice and all, it currently is not as helpful as it can be. For example we see that we got ``echo`` as a positional argument, but we don't know what it does, other than by guessing or by reading the source code. So, let's make it a bit more useful::"
msgstr "با این حال توجه داشته باشید که، اگرچه نمایش راهنما زیبا به نظر می‌رسد، اما در حال حاضر آن‌قدر که می‌تواند مفید نیست. برای مثال می‌بینیم که ``echo`` را به‌عنوان یک آرگومان جایگاهی داریم، اما نمی‌دانیم چه کاری انجام می‌دهد، مگر با حدس زدن یا خواندن کد منبع. بنابراین، بیایید آن را کمی مفیدتر کنیم::"

msgid ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"echo\", help=\"echo the string you use here\")\n"
"args = parser.parse_args()\n"
"print(args.echo)"
msgstr ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"echo\", help=\"echo the string you use here\")\n"
"args = parser.parse_args()\n"
"print(args.echo)"

msgid "And we get:"
msgstr "و این نتیجه را می‌گیریم:"

msgid ""
"$ python prog.py -h\n"
"usage: prog.py [-h] echo\n"
"\n"
"positional arguments:\n"
"  echo        echo the string you use here\n"
"\n"
"options:\n"
"  -h, --help  show this help message and exit"
msgstr ""
"$ python prog.py -h\n"
"usage: prog.py [-h] echo\n"
"\n"
"positional arguments:\n"
"  echo        echo the string you use here\n"
"\n"
"options:\n"
"  -h, --help  show this help message and exit"

msgid "Now, how about doing something even more useful::"
msgstr "حال، چطور است کاری حتی مفیدتر انجام دهیم::"

msgid ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"square\", help=\"display a square of a given number\")\n"
"args = parser.parse_args()\n"
"print(args.square**2)"
msgstr ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"square\", help=\"display a square of a given number\")\n"
"args = parser.parse_args()\n"
"print(args.square**2)"

msgid ""
"$ python prog.py 4\n"
"Traceback (most recent call last):\n"
"  File \"prog.py\", line 5, in <module>\n"
"    print(args.square**2)\n"
"TypeError: unsupported operand type(s) for ** or pow(): 'str' and 'int'"
msgstr ""
"$ python prog.py 4\n"
"Traceback (most recent call last):\n"
"  File \"prog.py\", line 5, in <module>\n"
"    print(args.square**2)\n"
"TypeError: unsupported operand type(s) for ** or pow(): 'str' and 'int'"

msgid "That didn't go so well. That's because :mod:`argparse` treats the options we give it as strings, unless we tell it otherwise. So, let's tell :mod:`argparse` to treat that input as an integer::"
msgstr "این کار چندان خوب پیش نرفت. دلیلش این است که :mod:`argparse` گزینه‌هایی را که به آن می‌دهیم به‌صورت رشته در نظر می‌گیرد، مگر اینکه طور دیگری به آن بگوییم. پس، بیایید به :mod:`argparse` بگوییم آن ورودی را به‌صورت عدد صحیح در نظر بگیرد::"

msgid ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"square\", help=\"display a square of a given number\",\n"
"                    type=int)\n"
"args = parser.parse_args()\n"
"print(args.square**2)"
msgstr ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"square\", help=\"display a square of a given number\",\n"
"                    type=int)\n"
"args = parser.parse_args()\n"
"print(args.square**2)"

msgid ""
"$ python prog.py 4\n"
"16\n"
"$ python prog.py four\n"
"usage: prog.py [-h] square\n"
"prog.py: error: argument square: invalid int value: 'four'"
msgstr ""
"$ python prog.py 4\n"
"16\n"
"$ python prog.py four\n"
"usage: prog.py [-h] square\n"
"prog.py: error: argument square: invalid int value: 'four'"

msgid "That went well. The program now even helpfully quits on bad illegal input before proceeding."
msgstr "این به‌خوبی پیش رفت. برنامه اکنون حتی در صورت ورودی بد و غیرمجاز، پیش از ادامه به‌صورت مفیدی خارج می‌شود."

msgid "Introducing Optional arguments"
msgstr "معرفی آرگومان‌های اختیاری"

msgid "So far we have been playing with positional arguments. Let us have a look on how to add optional ones::"
msgstr "تاکنون با آرگومان‌های جایگاهی کار کرده‌ایم. بگذارید نگاهی بیندازیم به چگونگی افزودن آرگومان‌های اختیاری::"

msgid ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"--verbosity\", help=\"increase output verbosity\")\n"
"args = parser.parse_args()\n"
"if args.verbosity:\n"
"    print(\"verbosity turned on\")"
msgstr ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"--verbosity\", help=\"increase output verbosity\")\n"
"args = parser.parse_args()\n"
"if args.verbosity:\n"
"    print(\"verbosity turned on\")"

msgid "And the output:"
msgstr "و خروجی:"

msgid ""
"$ python prog.py --verbosity 1\n"
"verbosity turned on\n"
"$ python prog.py\n"
"$ python prog.py --help\n"
"usage: prog.py [-h] [--verbosity VERBOSITY]\n"
"\n"
"options:\n"
"  -h, --help            show this help message and exit\n"
"  --verbosity VERBOSITY\n"
"                        increase output verbosity\n"
"$ python prog.py --verbosity\n"
"usage: prog.py [-h] [--verbosity VERBOSITY]\n"
"prog.py: error: argument --verbosity: expected one argument"
msgstr ""
"$ python prog.py --verbosity 1\n"
"verbosity turned on\n"
"$ python prog.py\n"
"$ python prog.py --help\n"
"usage: prog.py [-h] [--verbosity VERBOSITY]\n"
"\n"
"options:\n"
"  -h, --help            show this help message and exit\n"
"  --verbosity VERBOSITY\n"
"                        increase output verbosity\n"
"$ python prog.py --verbosity\n"
"usage: prog.py [-h] [--verbosity VERBOSITY]\n"
"prog.py: error: argument --verbosity: expected one argument"

msgid "The program is written so as to display something when ``--verbosity`` is specified and display nothing when not."
msgstr "این برنامه به‌گونه‌ای نوشته شده است که هنگام مشخص شدن ``--verbosity`` چیزی نمایش دهد و در غیر این صورت هیچ چیز نمایش ندهد."

msgid "To show that the option is actually optional, there is no error when running the program without it. Note that by default, if an optional argument isn't used, the relevant variable, in this case ``args.verbosity``, is given ``None`` as a value, which is the reason it fails the truth test of the :keyword:`if` statement."
msgstr "برای نشان دادن این که گزینه واقعاً اختیاری است، هنگام اجرای برنامه بدون آن هیچ خطایی رخ نمی‌دهد. توجه داشته باشید که به‌طور پیش‌فرض، اگر یک آرگومان اختیاری استفاده نشود، به متغیر مربوطه، در این مورد ``args.verbosity``، مقدار ``None`` داده می‌شود، که به همین دلیل در آزمون درستی دستور :keyword:`if` مردود می‌شود."

msgid "The help message is a bit different."
msgstr "پیام راهنما کمی متفاوت است."

msgid "When using the ``--verbosity`` option, one must also specify some value, any value."
msgstr "هنگام استفاده از گزینه ``--verbosity``، باید مقداری را نیز مشخص کنید؛ هر مقداری."

msgid "The above example accepts arbitrary integer values for ``--verbosity``, but for our simple program, only two values are actually useful, ``True`` or ``False``. Let's modify the code accordingly::"
msgstr "مثال بالا هر مقدار عدد صحیحی را برای ``--verbosity`` می‌پذیرد، اما برای برنامه ساده ما، تنها دو مقدار واقعاً مفید هستند: ``True`` یا ``False``. بیایید کد را بر همین اساس اصلاح کنیم::"

msgid ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"--verbose\", help=\"increase output verbosity\",\n"
"                    action=\"store_true\")\n"
"args = parser.parse_args()\n"
"if args.verbose:\n"
"    print(\"verbosity turned on\")"
msgstr ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"--verbose\", help=\"increase output verbosity\",\n"
"                    action=\"store_true\")\n"
"args = parser.parse_args()\n"
"if args.verbose:\n"
"    print(\"verbosity turned on\")"

msgid ""
"$ python prog.py --verbose\n"
"verbosity turned on\n"
"$ python prog.py --verbose 1\n"
"usage: prog.py [-h] [--verbose]\n"
"prog.py: error: unrecognized arguments: 1\n"
"$ python prog.py --help\n"
"usage: prog.py [-h] [--verbose]\n"
"\n"
"options:\n"
"  -h, --help  show this help message and exit\n"
"  --verbose   increase output verbosity"
msgstr ""
"$ python prog.py --verbose\n"
"verbosity turned on\n"
"$ python prog.py --verbose 1\n"
"usage: prog.py [-h] [--verbose]\n"
"prog.py: error: unrecognized arguments: 1\n"
"$ python prog.py --help\n"
"usage: prog.py [-h] [--verbose]\n"
"\n"
"options:\n"
"  -h, --help  show this help message and exit\n"
"  --verbose   increase output verbosity"

msgid "The option is now more of a flag than something that requires a value. We even changed the name of the option to match that idea. Note that we now specify a new keyword, ``action``, and give it the value ``\"store_true\"``. This means that, if the option is specified, assign the value ``True`` to ``args.verbose``. Not specifying it implies ``False``."
msgstr "این گزینه اکنون بیشتر یک پرچم است تا چیزی که به یک مقدار نیاز داشته باشد. ما حتی نام گزینه را برای هماهنگی با همین ایده تغییر دادیم. توجه کنید که اکنون یک کلیدواژه جدید، ``action``، مشخص می‌کنیم و مقدار ``\"store_true\"`` را به آن می‌دهیم. این بدان معناست که اگر گزینه مشخص شده باشد، مقدار ``True`` به ``args.verbose`` اختصاص داده می‌شود. مشخص نکردن آن به‌معنای ``False`` است."

msgid "It complains when you specify a value, in true spirit of what flags actually are."
msgstr "هنگامی که مقداری را تعیین می‌کنید، اعتراض می‌کند؛ دقیقاً مطابق با ماهیت واقعی پرچم‌ها (flags)."

msgid "Notice the different help text."
msgstr "به متن راهنمای متفاوت توجه کنید."

msgid "Short options"
msgstr "گزینه‌های کوتاه"

msgid "If you are familiar with command line usage, you will notice that I haven't yet touched on the topic of short versions of the options. It's quite simple::"
msgstr "اگر با استفاده از خط فرمان آشنا باشید، متوجه خواهید شد که هنوز به موضوع شکل‌های کوتاه گزینه‌ها نپرداخته‌ام. این موضوع کاملاً ساده است::"

msgid ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"-v\", \"--verbose\", help=\"increase output verbosity\",\n"
"                    action=\"store_true\")\n"
"args = parser.parse_args()\n"
"if args.verbose:\n"
"    print(\"verbosity turned on\")"
msgstr ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"-v\", \"--verbose\", help=\"increase output verbosity\",\n"
"                    action=\"store_true\")\n"
"args = parser.parse_args()\n"
"if args.verbose:\n"
"    print(\"verbosity turned on\")"

msgid "And here goes:"
msgstr "و به این صورت است:"

msgid ""
"$ python prog.py -v\n"
"verbosity turned on\n"
"$ python prog.py --help\n"
"usage: prog.py [-h] [-v]\n"
"\n"
"options:\n"
"  -h, --help     show this help message and exit\n"
"  -v, --verbose  increase output verbosity"
msgstr ""
"$ python prog.py -v\n"
"پرگویی روشن شد\n"
"$ python prog.py --help\n"
"طرز استفاده: prog.py [-h] [-v]\n"
"\n"
"گزینه‌ها:\n"
"  -h, --help     نمایش این پیام راهنما و خروج\n"
"  -v, --verbose  افزایش پرگویی خروجی"

msgid "Note that the new ability is also reflected in the help text."
msgstr "توجه داشته باشید که قابلیت جدید نیز در متن راهنما منعکس شده است."

msgid "Combining Positional and Optional arguments"
msgstr "ترکیب آرگومان‌های جایگاهی و اختیاری"

msgid "Our program keeps growing in complexity::"
msgstr "برنامه‌ی ما از نظر پیچیدگی همچنان در حال رشد است::"

msgid ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"square\", type=int,\n"
"                    help=\"display a square of a given number\")\n"
"parser.add_argument(\"-v\", \"--verbose\", action=\"store_true\",\n"
"                    help=\"increase output verbosity\")\n"
"args = parser.parse_args()\n"
"answer = args.square**2\n"
"if args.verbose:\n"
"    print(f\"the square of {args.square} equals {answer}\")\n"
"else:\n"
"    print(answer)"
msgstr ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"square\", type=int,\n"
"                    help=\"display a square of a given number\")\n"
"parser.add_argument(\"-v\", \"--verbose\", action=\"store_true\",\n"
"                    help=\"increase output verbosity\")\n"
"args = parser.parse_args()\n"
"answer = args.square**2\n"
"if args.verbose:\n"
"    print(f\"the square of {args.square} equals {answer}\")\n"
"else:\n"
"    print(answer)"

msgid "And now the output:"
msgstr "و اکنون خروجی:"

msgid ""
"$ python prog.py\n"
"usage: prog.py [-h] [-v] square\n"
"prog.py: error: the following arguments are required: square\n"
"$ python prog.py 4\n"
"16\n"
"$ python prog.py 4 --verbose\n"
"the square of 4 equals 16\n"
"$ python prog.py --verbose 4\n"
"the square of 4 equals 16"
msgstr ""
"$ python prog.py\n"
"usage: prog.py [-h] [-v] square\n"
"prog.py: error: the following arguments are required: square\n"
"$ python prog.py 4\n"
"16\n"
"$ python prog.py 4 --verbose\n"
"the square of 4 equals 16\n"
"$ python prog.py --verbose 4\n"
"the square of 4 equals 16"

msgid "We've brought back a positional argument, hence the complaint."
msgstr "ما یک آرگومان جایگاهی را بازگردانده‌ایم، به همین دلیل این شکایت وجود دارد."

msgid "Note that the order does not matter."
msgstr "توجه داشته باشید که ترتیب مهم نیست."

msgid "How about we give this program of ours back the ability to have multiple verbosity values, and actually get to use them::"
msgstr "چطور است که توانایی داشتن چندین مقدار پرگویی (verbosity) را به این برنامه‌مان بازگردانیم و واقعاً از آن‌ها استفاده کنیم::"

msgid ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"square\", type=int,\n"
"                    help=\"display a square of a given number\")\n"
"parser.add_argument(\"-v\", \"--verbosity\", type=int,\n"
"                    help=\"increase output verbosity\")\n"
"args = parser.parse_args()\n"
"answer = args.square**2\n"
"if args.verbosity == 2:\n"
"    print(f\"the square of {args.square} equals {answer}\")\n"
"elif args.verbosity == 1:\n"
"    print(f\"{args.square}^2 == {answer}\")\n"
"else:\n"
"    print(answer)"
msgstr ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"square\", type=int,\n"
"                    help=\"display a square of a given number\")\n"
"parser.add_argument(\"-v\", \"--verbosity\", type=int,\n"
"                    help=\"increase output verbosity\")\n"
"args = parser.parse_args()\n"
"answer = args.square**2\n"
"if args.verbosity == 2:\n"
"    print(f\"the square of {args.square} equals {answer}\")\n"
"elif args.verbosity == 1:\n"
"    print(f\"{args.square}^2 == {answer}\")\n"
"else:\n"
"    print(answer)"

msgid ""
"$ python prog.py 4\n"
"16\n"
"$ python prog.py 4 -v\n"
"usage: prog.py [-h] [-v VERBOSITY] square\n"
"prog.py: error: argument -v/--verbosity: expected one argument\n"
"$ python prog.py 4 -v 1\n"
"4^2 == 16\n"
"$ python prog.py 4 -v 2\n"
"the square of 4 equals 16\n"
"$ python prog.py 4 -v 3\n"
"16"
msgstr ""
"$ python prog.py 4\n"
"16\n"
"$ python prog.py 4 -v\n"
"usage: prog.py [-h] [-v VERBOSITY] square\n"
"prog.py: error: argument -v/--verbosity: expected one argument\n"
"$ python prog.py 4 -v 1\n"
"4^2 == 16\n"
"$ python prog.py 4 -v 2\n"
"the square of 4 equals 16\n"
"$ python prog.py 4 -v 3\n"
"16"

msgid "These all look good except the last one, which exposes a bug in our program. Let's fix it by restricting the values the ``--verbosity`` option can accept::"
msgstr "همه‌ی این‌ها خوب به نظر می‌رسند، به‌جز آخرین مورد که یک خطا را در برنامه‌ی ما آشکار می‌کند. بیایید آن را با محدود کردن مقادیری که گزینه‌ی ``--verbosity`` می‌تواند بپذیرد، اصلاح کنیم::"

msgid ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"square\", type=int,\n"
"                    help=\"display a square of a given number\")\n"
"parser.add_argument(\"-v\", \"--verbosity\", type=int, choices=[0, 1, 2],\n"
"                    help=\"increase output verbosity\")\n"
"args = parser.parse_args()\n"
"answer = args.square**2\n"
"if args.verbosity == 2:\n"
"    print(f\"the square of {args.square} equals {answer}\")\n"
"elif args.verbosity == 1:\n"
"    print(f\"{args.square}^2 == {answer}\")\n"
"else:\n"
"    print(answer)"
msgstr ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"square\", type=int,\n"
"                    help=\"display a square of a given number\")\n"
"parser.add_argument(\"-v\", \"--verbosity\", type=int, choices=[0, 1, 2],\n"
"                    help=\"increase output verbosity\")\n"
"args = parser.parse_args()\n"
"answer = args.square**2\n"
"if args.verbosity == 2:\n"
"    print(f\"the square of {args.square} equals {answer}\")\n"
"elif args.verbosity == 1:\n"
"    print(f\"{args.square}^2 == {answer}\")\n"
"else:\n"
"    print(answer)"

msgid ""
"$ python prog.py 4 -v 3\n"
"usage: prog.py [-h] [-v {0,1,2}] square\n"
"prog.py: error: argument -v/--verbosity: invalid choice: 3 (choose from 0, 1, 2)\n"
"$ python prog.py 4 -h\n"
"usage: prog.py [-h] [-v {0,1,2}] square\n"
"\n"
"positional arguments:\n"
"  square                display a square of a given number\n"
"\n"
"options:\n"
"  -h, --help            show this help message and exit\n"
"  -v, --verbosity {0,1,2}\n"
"                        increase output verbosity"
msgstr ""
"$ python prog.py 4 -v 3\n"
"usage: prog.py [-h] [-v {0,1,2}] square\n"
"prog.py: error: argument -v/--verbosity: invalid choice: 3 (choose from 0, 1, 2)\n"
"$ python prog.py 4 -h\n"
"usage: prog.py [-h] [-v {0,1,2}] square\n"
"\n"
"positional arguments:\n"
"  square                display a square of a given number\n"
"\n"
"options:\n"
"  -h, --help            show this help message and exit\n"
"  -v, --verbosity {0,1,2}\n"
"                        increase output verbosity"

msgid "Note that the change also reflects both in the error message as well as the help string."
msgstr "توجه داشته باشید که این تغییر هم در پیام خطا و هم در رشته راهنما منعکس می‌شود."

msgid "Now, let's use a different approach of playing with verbosity, which is pretty common. It also matches the way the CPython executable handles its own verbosity argument (check the output of ``python --help``)::"
msgstr "اکنون، بیایید از رویکرد متفاوتی برای بازی با سطح جزئیات استفاده کنیم، که نسبتاً رایج است. این روش همچنین با شیوه‌ای که پرونده اجرایی CPython آرگومان سطح جزئیات خود را مدیریت می‌کند مطابقت دارد (خروجی ``python --help`` را بررسی کنید)::"

msgid ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"square\", type=int,\n"
"                    help=\"display the square of a given number\")\n"
"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\",\n"
"                    help=\"increase output verbosity\")\n"
"args = parser.parse_args()\n"
"answer = args.square**2\n"
"if args.verbosity == 2:\n"
"    print(f\"the square of {args.square} equals {answer}\")\n"
"elif args.verbosity == 1:\n"
"    print(f\"{args.square}^2 == {answer}\")\n"
"else:\n"
"    print(answer)"
msgstr ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"square\", type=int,\n"
"                    help=\"display the square of a given number\")\n"
"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\",\n"
"                    help=\"increase output verbosity\")\n"
"args = parser.parse_args()\n"
"answer = args.square**2\n"
"if args.verbosity == 2:\n"
"    print(f\"the square of {args.square} equals {answer}\")\n"
"elif args.verbosity == 1:\n"
"    print(f\"{args.square}^2 == {answer}\")\n"
"else:\n"
"    print(answer)"

msgid "We have introduced another action, \"count\", to count the number of occurrences of specific options."
msgstr "ما اکشن دیگری به نام \"count\" برای شمارش تعداد دفعات استفاده از گزینه‌های خاص معرفی کرده‌ایم."

msgid ""
"$ python prog.py 4\n"
"16\n"
"$ python prog.py 4 -v\n"
"4^2 == 16\n"
"$ python prog.py 4 -vv\n"
"the square of 4 equals 16\n"
"$ python prog.py 4 --verbosity --verbosity\n"
"the square of 4 equals 16\n"
"$ python prog.py 4 -v 1\n"
"usage: prog.py [-h] [-v] square\n"
"prog.py: error: unrecognized arguments: 1\n"
"$ python prog.py 4 -h\n"
"usage: prog.py [-h] [-v] square\n"
"\n"
"positional arguments:\n"
"  square           display a square of a given number\n"
"\n"
"options:\n"
"  -h, --help       show this help message and exit\n"
"  -v, --verbosity  increase output verbosity\n"
"$ python prog.py 4 -vvv\n"
"16"
msgstr ""
"$ python prog.py 4\n"
"16\n"
"$ python prog.py 4 -v\n"
"4^2 == 16\n"
"$ python prog.py 4 -vv\n"
"the square of 4 equals 16\n"
"$ python prog.py 4 --verbosity --verbosity\n"
"the square of 4 equals 16\n"
"$ python prog.py 4 -v 1\n"
"usage: prog.py [-h] [-v] square\n"
"prog.py: error: unrecognized arguments: 1\n"
"$ python prog.py 4 -h\n"
"usage: prog.py [-h] [-v] square\n"
"\n"
"positional arguments:\n"
"  square           display a square of a given number\n"
"\n"
"options:\n"
"  -h, --help       show this help message and exit\n"
"  -v, --verbosity  increase output verbosity\n"
"$ python prog.py 4 -vvv\n"
"16"

msgid "Yes, it's now more of a flag (similar to ``action=\"store_true\"``) in the previous version of our script. That should explain the complaint."
msgstr "بله، اکنون در نسخه‌ی پیشین اسکریپت ما، بیشتر حکم یک پرچم را دارد (مشابه ``action=\"store_true\"``). این باید دلیل آن شکایت را توضیح دهد."

msgid "It also behaves similar to \"store_true\" action."
msgstr "همچنین رفتاری مشابه اکشن \"store_true\" دارد."

msgid "Now here's a demonstration of what the \"count\" action gives. You've probably seen this sort of usage before."
msgstr "اکنون در اینجا نمونه‌ای از آنچه کنش «count» ارائه می‌دهد آمده است. شما احتمالاً پیش‌تر این نوع استفاده را دیده‌اید."

msgid "And if you don't specify the ``-v`` flag, that flag is considered to have ``None`` value."
msgstr "و اگر پرچم ``-v`` را مشخص نکنید، آن پرچم دارای مقدار ``None`` در نظر گرفته می‌شود."

msgid "As should be expected, specifying the long form of the flag, we should get the same output."
msgstr "همان‌طور که انتظار می‌رود، با مشخص کردن شکل بلند پرچم، باید همان خروجی را دریافت کنیم."

msgid "Sadly, our help output isn't very informative on the new ability our script has acquired, but that can always be fixed by improving the documentation for our script (e.g. via the ``help`` keyword argument)."
msgstr "متأسفانه، خروجی راهنمای ما چندان درباره قابلیت جدیدی که اسکریپت ما کسب کرده است، گویا نیست، اما همیشه می‌توان این مشکل را با بهبود مستندات اسکریپت خود برطرف کرد (مثلاً از طریق آرگومان کلیدواژه‌ای ``help``)."

msgid "That last output exposes a bug in our program."
msgstr "آن آخرین خروجی، اشکالی را در برنامه‌ی ما آشکار می‌کند."

msgid "Let's fix::"
msgstr "بیایید آن را اصلاح کنیم::"

msgid ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"square\", type=int,\n"
"                    help=\"display a square of a given number\")\n"
"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\",\n"
"                    help=\"increase output verbosity\")\n"
"args = parser.parse_args()\n"
"answer = args.square**2\n"
"\n"
"# bugfix: replace == with >=\n"
"if args.verbosity >= 2:\n"
"    print(f\"the square of {args.square} equals {answer}\")\n"
"elif args.verbosity >= 1:\n"
"    print(f\"{args.square}^2 == {answer}\")\n"
"else:\n"
"    print(answer)"
msgstr ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"square\", type=int,\n"
"                    help=\"display a square of a given number\")\n"
"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\",\n"
"                    help=\"increase output verbosity\")\n"
"args = parser.parse_args()\n"
"answer = args.square**2\n"
"\n"
"# bugfix: replace == with >=\n"
"if args.verbosity >= 2:\n"
"    print(f\"the square of {args.square} equals {answer}\")\n"
"elif args.verbosity >= 1:\n"
"    print(f\"{args.square}^2 == {answer}\")\n"
"else:\n"
"    print(answer)"

msgid "And this is what it gives:"
msgstr "و این چیزی است که به دست می‌دهد:"

msgid ""
"$ python prog.py 4 -vvv\n"
"the square of 4 equals 16\n"
"$ python prog.py 4 -vvvv\n"
"the square of 4 equals 16\n"
"$ python prog.py 4\n"
"Traceback (most recent call last):\n"
"  File \"prog.py\", line 11, in <module>\n"
"    if args.verbosity >= 2:\n"
"TypeError: '>=' not supported between instances of 'NoneType' and 'int'"
msgstr ""
"$ python prog.py 4 -vvv\n"
"the square of 4 equals 16\n"
"$ python prog.py 4 -vvvv\n"
"the square of 4 equals 16\n"
"$ python prog.py 4\n"
"Traceback (most recent call last):\n"
"  File \"prog.py\", line 11, in <module>\n"
"    if args.verbosity >= 2:\n"
"TypeError: '>=' not supported between instances of 'NoneType' and 'int'"

msgid "First output went well, and fixes the bug we had before. That is, we want any value >= 2 to be as verbose as possible."
msgstr "خروجی نخست به‌خوبی پیش رفت و اشکالی را که پیش‌تر داشتیم برطرف می‌کند. یعنی می‌خواهیم هر مقدار >= 2 تا حد ممکن پُرگویی داشته باشد."

msgid "Third output not so good."
msgstr "خروجی سوم چندان خوب نیست."

msgid "Let's fix that bug::"
msgstr "بیایید آن اشکال را برطرف کنیم::"

msgid ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"square\", type=int,\n"
"                    help=\"display a square of a given number\")\n"
"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\", default=0,\n"
"                    help=\"increase output verbosity\")\n"
"args = parser.parse_args()\n"
"answer = args.square**2\n"
"if args.verbosity >= 2:\n"
"    print(f\"the square of {args.square} equals {answer}\")\n"
"elif args.verbosity >= 1:\n"
"    print(f\"{args.square}^2 == {answer}\")\n"
"else:\n"
"    print(answer)"
msgstr ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"square\", type=int,\n"
"                    help=\"display a square of a given number\")\n"
"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\", default=0,\n"
"                    help=\"increase output verbosity\")\n"
"args = parser.parse_args()\n"
"answer = args.square**2\n"
"if args.verbosity >= 2:\n"
"    print(f\"the square of {args.square} equals {answer}\")\n"
"elif args.verbosity >= 1:\n"
"    print(f\"{args.square}^2 == {answer}\")\n"
"else:\n"
"    print(answer)"

msgid "We've just introduced yet another keyword, ``default``. We've set it to ``0`` in order to make it comparable to the other int values. Remember that by default, if an optional argument isn't specified, it gets the ``None`` value, and that cannot be compared to an int value (hence the :exc:`TypeError` exception)."
msgstr "ما همین حالا کلیدواژه‌ی دیگری به نام ``default`` را معرفی کردیم. ما آن را روی ``0`` تنظیم کرده‌ایم تا بتوان آن را با سایر مقادیر عدد صحیح مقایسه کرد. به خاطر داشته باشید که به‌طور پیش‌فرض، اگر آرگومان اختیاری مشخص نشده باشد، مقدار ``None`` را دریافت می‌کند و نمی‌توان آن را با یک مقدار عدد صحیح مقایسه کرد (از این رو استثنای :exc:`TypeError` رخ می‌دهد)."

msgid "And:"
msgstr "و:"

msgid ""
"$ python prog.py 4\n"
"16"
msgstr ""
"$ python prog.py 4\n"
"16"

msgid "You can go quite far just with what we've learned so far, and we have only scratched the surface. The :mod:`argparse` module is very powerful, and we'll explore a bit more of it before we end this tutorial."
msgstr "شما می‌توانید فقط با آنچه تاکنون آموخته‌ایم بسیار پیش بروید، و ما تنها سطح آن را خراش داده‌ایم. ماژول :mod:`argparse` بسیار قدرتمند است و پیش از پایان این آموزش، کمی بیشتر آن را بررسی خواهیم کرد."

msgid "Getting a little more advanced"
msgstr "کمی پیشرفته‌تر"

msgid "What if we wanted to expand our tiny program to perform other powers, not just squares::"
msgstr "اگر بخواهیم برنامه‌ی کوچک خود را برای محاسبه‌ی توان‌های دیگر، نه فقط مربع‌ها، گسترش دهیم::"

msgid ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"x\", type=int, help=\"the base\")\n"
"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n"
"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\", default=0)\n"
"args = parser.parse_args()\n"
"answer = args.x**args.y\n"
"if args.verbosity >= 2:\n"
"    print(f\"{args.x} to the power {args.y} equals {answer}\")\n"
"elif args.verbosity >= 1:\n"
"    print(f\"{args.x}^{args.y} == {answer}\")\n"
"else:\n"
"    print(answer)"
msgstr ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"x\", type=int, help=\"the base\")\n"
"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n"
"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\", default=0)\n"
"args = parser.parse_args()\n"
"answer = args.x**args.y\n"
"if args.verbosity >= 2:\n"
"    print(f\"{args.x} to the power {args.y} equals {answer}\")\n"
"elif args.verbosity >= 1:\n"
"    print(f\"{args.x}^{args.y} == {answer}\")\n"
"else:\n"
"    print(answer)"

msgid "Output:"
msgstr "خروجی:"

msgid ""
"$ python prog.py\n"
"usage: prog.py [-h] [-v] x y\n"
"prog.py: error: the following arguments are required: x, y\n"
"$ python prog.py -h\n"
"usage: prog.py [-h] [-v] x y\n"
"\n"
"positional arguments:\n"
"  x                the base\n"
"  y                the exponent\n"
"\n"
"options:\n"
"  -h, --help       show this help message and exit\n"
"  -v, --verbosity\n"
"$ python prog.py 4 2 -v\n"
"4^2 == 16"
msgstr ""
"$ python prog.py\n"
"usage: prog.py [-h] [-v] x y\n"
"prog.py: error: the following arguments are required: x, y\n"
"$ python prog.py -h\n"
"usage: prog.py [-h] [-v] x y\n"
"\n"
"positional arguments:\n"
"  x                the base\n"
"  y                the exponent\n"
"\n"
"options:\n"
"  -h, --help       show this help message and exit\n"
"  -v, --verbosity\n"
"$ python prog.py 4 2 -v\n"
"4^2 == 16"

msgid "Notice that so far we've been using verbosity level to *change* the text that gets displayed. The following example instead uses verbosity level to display *more* text instead::"
msgstr "توجه کنید که تاکنون از سطح پرگویی برای *تغییر* متنی که نمایش داده می‌شود استفاده کرده‌ایم. مثال زیر به‌جای آن از سطح پرگویی برای نمایش متن *بیشتر* استفاده می‌کند::"

msgid ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"x\", type=int, help=\"the base\")\n"
"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n"
"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\", default=0)\n"
"args = parser.parse_args()\n"
"answer = args.x**args.y\n"
"if args.verbosity >= 2:\n"
"    print(f\"Running '{__file__}'\")\n"
"if args.verbosity >= 1:\n"
"    print(f\"{args.x}^{args.y} == \", end=\"\")\n"
"print(answer)"
msgstr ""
"import argparse\n"
"parser = argparse.ArgumentParser()\n"
"parser.add_argument(\"x\", type=int, help=\"the base\")\n"
"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n"
"parser.add_argument(\"-v\", \"--verbosity\", action=\"count\", default=0)\n"
"args = parser.parse_args()\n"
"answer = args.x**args.y\n"
"if args.verbosity >= 2:\n"
"    print(f\"Running '{__file__}'\")\n"
"if args.verbosity >= 1:\n"
"    print(f\"{args.x}^{args.y} == \", end=\"\")\n"
"print(answer)"

msgid ""
"$ python prog.py 4 2\n"
"16\n"
"$ python prog.py 4 2 -v\n"
"4^2 == 16\n"
"$ python prog.py 4 2 -vv\n"
"Running 'prog.py'\n"
"4^2 == 16"
msgstr ""
"$ python prog.py 4 2\n"
"16\n"
"$ python prog.py 4 2 -v\n"
"4^2 == 16\n"
"$ python prog.py 4 2 -vv\n"
"Running 'prog.py'\n"
"4^2 == 16"

msgid "Specifying ambiguous arguments"
msgstr "مشخص کردن آرگومان‌های مبهم"

msgid "When there is ambiguity in deciding whether an argument is positional or for an argument, ``--`` can be used to tell :meth:`~ArgumentParser.parse_args` that everything after that is a positional argument::"
msgstr "هنگامی که در تشخیص اینکه یک آرگومان جایگاهی است یا برای یک آرگومان است، ابهام وجود داشته باشد، می‌توان از ``--`` استفاده کرد تا به :meth:`~ArgumentParser.parse_args` گفته شود که همه‌چیز پس از آن یک آرگومان جایگاهی است::"

msgid ""
">>> parser = argparse.ArgumentParser(prog='PROG')\n"
">>> parser.add_argument('-n', nargs='+')\n"
">>> parser.add_argument('args', nargs='*')\n"
"\n"
">>> # ambiguous, so parse_args assumes it's an option\n"
">>> parser.parse_args(['-f'])\n"
"usage: PROG [-h] [-n N [N ...]] [args ...]\n"
"PROG: error: unrecognized arguments: -f\n"
"\n"
">>> parser.parse_args(['--', '-f'])\n"
"Namespace(args=['-f'], n=None)\n"
"\n"
">>> # ambiguous, so the -n option greedily accepts arguments\n"
">>> parser.parse_args(['-n', '1', '2', '3'])\n"
"Namespace(args=[], n=['1', '2', '3'])\n"
"\n"
">>> parser.parse_args(['-n', '1', '--', '2', '3'])\n"
"Namespace(args=['2', '3'], n=['1'])"
msgstr ""
">>> parser = argparse.ArgumentParser(prog='PROG')\n"
">>> parser.add_argument('-n', nargs='+')\n"
">>> parser.add_argument('args', nargs='*')\n"
"\n"
">>> # ambiguous, so parse_args assumes it's an option\n"
">>> parser.parse_args(['-f'])\n"
"usage: PROG [-h] [-n N [N ...]] [args ...]\n"
"PROG: error: unrecognized arguments: -f\n"
"\n"
">>> parser.parse_args(['--', '-f'])\n"
"Namespace(args=['-f'], n=None)\n"
"\n"
">>> # ambiguous, so the -n option greedily accepts arguments\n"
">>> parser.parse_args(['-n', '1', '2', '3'])\n"
"Namespace(args=[], n=['1', '2', '3'])\n"
"\n"
">>> parser.parse_args(['-n', '1', '--', '2', '3'])\n"
"Namespace(args=['2', '3'], n=['1'])"

msgid "Conflicting options"
msgstr "گزینه‌های متعارض"

msgid "So far, we have been working with two methods of an :class:`argparse.ArgumentParser` instance. Let's introduce a third one, :meth:`~ArgumentParser.add_mutually_exclusive_group`. It allows for us to specify options that conflict with each other. Let's also change the rest of the program so that the new functionality makes more sense: we'll introduce the ``--quiet`` option, which will be the opposite of the ``--verbose`` one::"
msgstr "تاکنون، با دو متد از یک نمونه‌ی :class:`argparse.ArgumentParser` کار کرده‌ایم. بیایید متد سومی را معرفی کنیم، :meth:`~ArgumentParser.add_mutually_exclusive_group`. این متد به ما امکان می‌دهد گزینه‌هایی را مشخص کنیم که با یکدیگر ناسازگارند. بیایید همچنین سایر بخش‌های برنامه را تغییر دهیم تا قابلیت جدید منطقی‌تر باشد: گزینه‌ی ``--quiet`` را معرفی خواهیم کرد، که متضاد گزینه‌ی ``--verbose`` خواهد بود::"

msgid ""
"import argparse\n"
"\n"
"parser = argparse.ArgumentParser()\n"
"group = parser.add_mutually_exclusive_group()\n"
"group.add_argument(\"-v\", \"--verbose\", action=\"store_true\")\n"
"group.add_argument(\"-q\", \"--quiet\", action=\"store_true\")\n"
"parser.add_argument(\"x\", type=int, help=\"the base\")\n"
"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n"
"args = parser.parse_args()\n"
"answer = args.x**args.y\n"
"\n"
"if args.quiet:\n"
"    print(answer)\n"
"elif args.verbose:\n"
"    print(f\"{args.x} to the power {args.y} equals {answer}\")\n"
"else:\n"
"    print(f\"{args.x}^{args.y} == {answer}\")"
msgstr ""
"import argparse\n"
"\n"
"parser = argparse.ArgumentParser()\n"
"group = parser.add_mutually_exclusive_group()\n"
"group.add_argument(\"-v\", \"--verbose\", action=\"store_true\")\n"
"group.add_argument(\"-q\", \"--quiet\", action=\"store_true\")\n"
"parser.add_argument(\"x\", type=int, help=\"the base\")\n"
"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n"
"args = parser.parse_args()\n"
"answer = args.x**args.y\n"
"\n"
"if args.quiet:\n"
"    print(answer)\n"
"elif args.verbose:\n"
"    print(f\"{args.x} to the power {args.y} equals {answer}\")\n"
"else:\n"
"    print(f\"{args.x}^{args.y} == {answer}\")"

msgid "Our program is now simpler, and we've lost some functionality for the sake of demonstration. Anyways, here's the output:"
msgstr "برنامه‌ی ما اکنون ساده‌تر است و برخی قابلیت‌ها را به‌منظور نمایش از دست داده‌ایم. به هر حال، خروجی به این صورت است:"

msgid ""
"$ python prog.py 4 2\n"
"4^2 == 16\n"
"$ python prog.py 4 2 -q\n"
"16\n"
"$ python prog.py 4 2 -v\n"
"4 to the power 2 equals 16\n"
"$ python prog.py 4 2 -vq\n"
"usage: prog.py [-h] [-v | -q] x y\n"
"prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose\n"
"$ python prog.py 4 2 -v --quiet\n"
"usage: prog.py [-h] [-v | -q] x y\n"
"prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose"
msgstr ""
"$ python prog.py 4 2\n"
"4^2 == 16\n"
"$ python prog.py 4 2 -q\n"
"16\n"
"$ python prog.py 4 2 -v\n"
"4 to the power 2 equals 16\n"
"$ python prog.py 4 2 -vq\n"
"usage: prog.py [-h] [-v | -q] x y\n"
"prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose\n"
"$ python prog.py 4 2 -v --quiet\n"
"usage: prog.py [-h] [-v | -q] x y\n"
"prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose"

msgid "That should be easy to follow. I've added that last output so you can see the sort of flexibility you get, i.e. mixing long form options with short form ones."
msgstr "این باید به‌راحتی قابل‌فهم باشد. آن خروجی پایانی را افزوده‌ام تا بتوانید نوع انعطاف‌پذیری‌ای را که در اختیار دارید ببینید، یعنی ترکیب گزینه‌های بلندبا با گزینه‌های کوتاه‌با."

msgid "Before we conclude, you probably want to tell your users the main purpose of your program, just in case they don't know::"
msgstr "پیش از آنکه به پایان برسیم، احتمالاً می‌خواهید هدف اصلی برنامه‌ی خود را به کاربران خود بگویید، فقط برای حالتی که نمی‌دانند::"

msgid ""
"import argparse\n"
"\n"
"parser = argparse.ArgumentParser(description=\"calculate X to the power of Y\")\n"
"group = parser.add_mutually_exclusive_group()\n"
"group.add_argument(\"-v\", \"--verbose\", action=\"store_true\")\n"
"group.add_argument(\"-q\", \"--quiet\", action=\"store_true\")\n"
"parser.add_argument(\"x\", type=int, help=\"the base\")\n"
"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n"
"args = parser.parse_args()\n"
"answer = args.x**args.y\n"
"\n"
"if args.quiet:\n"
"    print(answer)\n"
"elif args.verbose:\n"
"    print(f\"{args.x} to the power {args.y} equals {answer}\")\n"
"else:\n"
"    print(f\"{args.x}^{args.y} == {answer}\")"
msgstr ""
"import argparse\n"
"\n"
"parser = argparse.ArgumentParser(description=\"calculate X to the power of Y\")\n"
"group = parser.add_mutually_exclusive_group()\n"
"group.add_argument(\"-v\", \"--verbose\", action=\"store_true\")\n"
"group.add_argument(\"-q\", \"--quiet\", action=\"store_true\")\n"
"parser.add_argument(\"x\", type=int, help=\"the base\")\n"
"parser.add_argument(\"y\", type=int, help=\"the exponent\")\n"
"args = parser.parse_args()\n"
"answer = args.x**args.y\n"
"\n"
"if args.quiet:\n"
"    print(answer)\n"
"elif args.verbose:\n"
"    print(f\"{args.x} to the power {args.y} equals {answer}\")\n"
"else:\n"
"    print(f\"{args.x}^{args.y} == {answer}\")"

msgid "Note that slight difference in the usage text. Note the ``[-v | -q]``, which tells us that we can either use ``-v`` or ``-q``, but not both at the same time:"
msgstr "توجه کنید که تفاوت اندکی در متن کاربرد وجود دارد. به ``[-v | -q]`` توجه کنید، که به ما می‌گوید می‌توانیم از ``-v`` یا ``-q`` استفاده کنیم، اما نه هر دو به‌طور همزمان:"

msgid ""
"$ python prog.py --help\n"
"usage: prog.py [-h] [-v | -q] x y\n"
"\n"
"calculate X to the power of Y\n"
"\n"
"positional arguments:\n"
"  x              the base\n"
"  y              the exponent\n"
"\n"
"options:\n"
"  -h, --help     show this help message and exit\n"
"  -v, --verbose\n"
"  -q, --quiet"
msgstr ""
"$ python prog.py --help\n"
"نحوه استفاده: prog.py [-h] [-v | -q] x y\n"
"\n"
"X را به توان Y محاسبه می‌کند\n"
"\n"
"آرگومان‌های جایگاهی:\n"
"  x              پایه\n"
"  y              توان\n"
"\n"
"گزینه‌ها:\n"
"  -h, --help     نمایش این پیام راهنما و خروج\n"
"  -v, --verbose\n"
"  -q, --quiet"

msgid "How to translate the argparse output"
msgstr "چگونه خروجی argparse را ترجمه کنیم"

msgid "The output of the :mod:`argparse` module such as its help text and error messages are all made translatable using the :mod:`gettext` module. This allows applications to easily localize messages produced by :mod:`argparse`. See also :ref:`i18n-howto`."
msgstr "خروجی‌های ماژول :mod:`argparse` مانند متن راهنما و پیام‌های خطای آن، همگی با استفاده از ماژول :mod:`gettext` قابل ترجمه می‌شوند. این امکان را به برنامه‌ها می‌دهد تا پیام‌های تولیدشده توسط :mod:`argparse` را به‌سادگی بومی‌سازی کنند. همچنین :ref:`i18n-howto` را ببینید."

msgid "For instance, in this :mod:`argparse` output:"
msgstr "برای مثال، در این خروجی :mod:`argparse`:"

msgid "The strings ``usage:``, ``positional arguments:``, ``options:`` and ``show this help message and exit`` are all translatable."
msgstr "رشته‌های ``usage:``، ``positional arguments:``، ``options:`` و ``show this help message and exit`` همگی قابل ترجمه هستند."

msgid "In order to translate these strings, they must first be extracted into a ``.po`` file. For example, using `Babel <https://babel.pocoo.org/>`__, run this command:"
msgstr "برای ترجمه‌ی این رشته‌ها، ابتدا باید آن‌ها را به یک پرونده ``.po`` استخراج کنید. برای مثال، با استفاده از `Babel <https://babel.pocoo.org/>`__، این فرمان را اجرا کنید:"

msgid "$ pybabel extract -o messages.po /usr/lib/python3.12/argparse.py"
msgstr "$ pybabel extract -o messages.po /usr/lib/python3.12/argparse.py"

msgid "This command will extract all translatable strings from the :mod:`argparse` module and output them into a file named ``messages.po``. This command assumes that your Python installation is in ``/usr/lib``."
msgstr "این دستور تمام رشته‌های ترجمه‌پذیر را از ماژول :mod:`argparse` استخراج می‌کند و آن‌ها را در پرونده‌ای به نام ``messages.po`` خروجی می‌دهد. این دستور فرض می‌کند که نصب پایتون شما در ``/usr/lib`` قرار دارد."

msgid "You can find out the location of the :mod:`argparse` module on your system using this script::"
msgstr "شما می‌توانید با استفاده از این اسکریپت، محل ماژول :mod:`argparse` را در سیستم خود بیابید::"

msgid ""
"import argparse\n"
"print(argparse.__file__)"
msgstr ""
"import argparse\n"
"print(argparse.__file__)"

msgid "Once the messages in the ``.po`` file are translated and the translations are installed using :mod:`gettext`, :mod:`argparse` will be able to display the translated messages."
msgstr "پس از اینکه پیام‌های موجود در پرونده ``.po`` ترجمه شدند و ترجمه‌ها با استفاده از :mod:`gettext` نصب شدند، :mod:`argparse` می‌تواند پیام‌های ترجمه‌شده را نمایش دهد."

msgid "To translate your own strings in the :mod:`argparse` output, use :mod:`gettext`."
msgstr "برای ترجمه‌ی رشته‌های خودتان در خروجی :mod:`argparse`، از :mod:`gettext` استفاده کنید."

msgid "Custom type converters"
msgstr "مبدل‌های نوع سفارشی"

msgid "The :mod:`argparse` module allows you to specify custom type converters for your command-line arguments. This allows you to modify user input before it's stored in the :class:`argparse.Namespace`. This can be useful when you need to pre-process the input before it is used in your program."
msgstr "ماژول :mod:`argparse` به شما امکان می‌دهد مبدل‌های نوع سفارشی برای آرگومان‌های خط فرمان خود تعیین کنید. این امکان به شما اجازه می‌دهد ورودی کاربر را پیش از ذخیره شدن در :class:`argparse.Namespace` تغییر دهید. این می‌تواند زمانی مفید باشد که نیاز دارید ورودی را پیش از استفاده در برنامه‌تان پیش‌پردازش کنید."

msgid "When using a custom type converter, you can use any callable that takes a single string argument (the argument value) and returns the converted value. However, if you need to handle more complex scenarios, you can use a custom action class with the **action** parameter instead."
msgstr "هنگام استفاده از یک مبدل نوع سفارشی، می‌توانید از هر فراخوانی‌پذیری که یک آرگومان رشته‌ای دریافت می‌کند (مقدار آرگومان) و مقدار تبدیل‌شده را برمی‌گرداند، استفاده کنید. با این حال، اگر نیاز به مدیریت حالت‌های پیچیده‌تر دارید، می‌توانید به‌جای آن از یک کلاس اکشنسفارشی با پارامتر **action** استفاده کنید."

msgid "For example, let's say you want to handle arguments with different prefixes and process them accordingly::"
msgstr "برای مثال، فرض کنید می‌خواهید آرگومان‌هایی با پیشوندهای مختلف را مدیریت کنید و آن‌ها را بر همان اساس پردازش کنید::"

msgid ""
"import argparse\n"
"\n"
"parser = argparse.ArgumentParser(prefix_chars='-+')\n"
"\n"
"parser.add_argument('-a', metavar='<value>', action='append',\n"
"                    type=lambda x: ('-', x))\n"
"parser.add_argument('+a', metavar='<value>', action='append',\n"
"                    type=lambda x: ('+', x))\n"
"\n"
"args = parser.parse_args()\n"
"print(args)"
msgstr ""
"import argparse\n"
"\n"
"parser = argparse.ArgumentParser(prefix_chars='-+')\n"
"\n"
"parser.add_argument('-a', metavar='<value>', action='append',\n"
"                    type=lambda x: ('-', x))\n"
"parser.add_argument('+a', metavar='<value>', action='append',\n"
"                    type=lambda x: ('+', x))\n"
"\n"
"args = parser.parse_args()\n"
"print(args)"

msgid ""
"$ python prog.py -a value1 +a value2\n"
"Namespace(a=[('-', 'value1'), ('+', 'value2')])"
msgstr ""
"$ python prog.py -a value1 +a value2\n"
"Namespace(a=[('-', 'value1'), ('+', 'value2')])"

msgid "In this example, we:"
msgstr "در این مثال، ما:"

msgid "Created a parser with custom prefix characters using the ``prefix_chars`` parameter."
msgstr "یک پارسر با نویسه‌های پیشوند سفارشی با استفاده از پارامتر ``prefix_chars`` ایجاد شد."

msgid "Defined two arguments, ``-a`` and ``+a``, which used the ``type`` parameter to create custom type converters to store the value in a tuple with the prefix."
msgstr "دو آرگومان ``-a`` و ``+a`` تعریف شدند که از پارامتر ``type`` برای ایجاد مبدل‌های نوع سفارشی استفاده می‌کردند تا مقدار را در یک تاپلهمراه با پیشوند ذخیره کنند."

msgid "Without the custom type converters, the arguments would have treated the ``-a`` and ``+a`` as the same argument, which would have been undesirable. By using custom type converters, we were able to differentiate between the two arguments."
msgstr "بدون مبدل‌های نوع سفارشی، ``-a`` و ``+a`` به‌عنوان یک آرگومان یکسان تلقی می‌شدند، که این موضوع نامطلوب بود. با استفاده از مبدل‌های نوع سفارشی، توانستیم بین این دو آرگومان تمایز قائل شویم."

msgid "Conclusion"
msgstr "نتیجه‌گیری"

msgid "The :mod:`argparse` module offers a lot more than shown here. Its docs are quite detailed and thorough, and full of examples. Having gone through this tutorial, you should easily digest them without feeling overwhelmed."
msgstr "ماژول :mod:`argparse` امکانات بسیار بیشتری نسبت به آنچه در اینجا نشان داده شد ارائه می‌دهد. مستندات آن کاملاً دقیق و جامع و سرشار از مثال است. پس از گذراندن این آموزش، باید بتوانید به‌راحتی آن‌ها را درک کنید، بدون آن‌که احساس کنید مطالب برایتان سنگین است."

#~ msgid "author"
#~ msgstr "نویسنده"

#~ msgid "Tshepang Mbambo"
#~ msgstr "Tshepang Mbambo"