"Project-Id-Version: Python 3.14\n"

"Report-Msgid-Bugs-To: \n"

"POT-Creation-Date: 2026-09-19 20:08+0330\n"

"PO-Revision-Date: 2026-09-15 11:04+0330\n"

"Last-Translator: Sepehr Rasouli <[email protected]>, 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 "Modules"

msgstr "ماژول‌ها"

msgid "If you quit from the Python interpreter and enter it again, the definitions you have made (functions and variables) are lost. Therefore, if you want to write a somewhat longer program, you are better off using a text editor to prepare the input for the interpreter and running it with that file as input instead. This is known as creating a *script*. As your program gets longer, you may want to split it into several files for easier maintenance. You may also want to use a handy function that you've written in several programs without copying its definition into each program."

msgstr "اگر از مفسر پایتون خارج شوید و دوباره وارد آن شوید، تعریف‌هایی که ایجاد کرده‌اید (توابع و متغیرها) از بین می‌روند. بنابراین، اگر می‌خواهید برنامه‌ای نسبتاً طولانی‌تر بنویسید، بهتر است به‌جای آن از یک ویرایشگر متن برای آماده‌سازی ورودی مفسر استفاده کنید و آن را با استفاده از آن پرونده به‌عنوان ورودی اجرا کنید. این کار با نام ایجاد یک *اسکریپت* شناخته می‌شود. هرچه برنامه‌ی شما طولانی‌تر شود، ممکن است بخواهید آن را برای نگهداری آسان‌تر به چندین پرونده تقسیم کنید. همچنین ممکن است بخواهید از یک تابع کاربردی که در چندین برنامه نوشته‌اید، بدون کپی کردن تعریف آن در هر برنامه استفاده کنید."

msgid "To support this, Python has a way to put definitions in a file and use them in a script or in an interactive instance of the interpreter. Such a file is called a *module*; definitions from a module can be *imported* into other modules or into the *main* module (the collection of variables that you have access to in a script executed at the top level and in calculator mode)."

msgstr "برای پشتیبانی از این کار، پایتون روشی دارد که به شما اجازه می‌دهد تعریف‌ها را در یک پرونده قرار دهید و از آن‌ها در یک اسکریپت یا در یک نمونه‌ی تعاملی از مفسر استفاده کنید. چنین پرونده‌ای یک *ماژول* نامیده می‌شود؛ تعریف‌های یک ماژول را می‌توان به ماژول‌های دیگر یا به ماژول *اصلی* (*main*) (مجموعه‌ای از متغیرهایی که در یک اسکریپت اجراشده در سطح بالا و در حالت ماشین‌حساب به آن‌ها دسترسی دارید) *ایمپورت* کرد."

msgid "A module is a file containing Python definitions and statements. The file name is the module name with the suffix :file:`.py` appended. Within a module, the module's name (as a string) is available as the value of the global variable ``__name__``. For instance, use your favorite text editor to create a file called :file:`fibo.py` in the current directory with the following contents::"

msgstr "یک ماژول پرونده‌ای است که شامل تعریف‌ها و دستورهای پایتون است. نام پرونده، نام ماژول به‌همراه پسوند :file:`.py` است. درون یک ماژول، نام ماژول (به‌صورت یک رشته) به‌عنوان مقدار متغیر سراسری ``__name__`` در دسترس است. برای نمونه، با استفاده از ویرایشگر متن دلخواه خود پرونده‌ای با نام :file:`fibo.py` را در پوشه‌ی جاری ایجاد کنید که محتوای زیر را داشته باشد::"

msgid ""

msgstr ""

msgid "Now enter the Python interpreter and import this module with the following command::"

msgstr "اکنون وارد مفسر پایتون شوید و این ماژول را با دستور زیر ایمپورت کنید::"

msgid ">>> import fibo"

msgstr ">>> import fibo"

msgid "This does not add the names of the functions defined in ``fibo`` directly to the current :term:`namespace` (see :ref:`tut-scopes` for more details); it only adds the module name ``fibo`` there. Using the module name you can access the functions::"

msgstr "این کار نام توابعی را که در ``fibo`` تعریف شده‌اند، مستقیماً به :term:`فضای نام <namespace>` فعلی اضافه نمی‌کند (برای جزئیات بیشتر به :ref:`tut-scopes` مراجعه کنید)؛ بلکه فقط نام ماژول ``fibo`` را به آن اضافه می‌کند. با استفاده از نام ماژول می‌توانید به توابع دسترسی پیدا کنید::"

msgid ""

msgstr ""

msgid "If you intend to use a function often you can assign it to a local name::"

msgstr "اگر قصد دارید از یک تابع به‌طور مکرر استفاده کنید، می‌توانید آن را به یک نام محلی اختصاص دهید::"

msgid ""

msgstr ""

msgid "More on Modules"

msgstr "بیشتر درباره‌ی ماژول‌ها"

msgid "A module can contain executable statements as well as function definitions. These statements are intended to initialize the module. They are executed only the *first* time the module name is encountered in an import statement. [#]_ (They are also run if the file is executed as a script.)"

msgstr "یک ماژول می‌تواند علاوه بر تعریف توابع، شامل دستورهای اجرایی نیز باشد. هدف از این دستورها مقداردهی اولیه‌ی ماژول است. این دستورها فقط در *اولین* باری که نام ماژول در یک دستور ایمپورت دیده می‌شود اجرا می‌شوند. [#]_ (همچنین اگر پرونده به‌عنوان یک اسکریپت اجرا شود، این دستورها اجرا خواهند شد.)"

msgid "Each module has its own private namespace, which is used as the global namespace by all functions defined in the module. Thus, the author of a module can use global variables in the module without worrying about accidental clashes with a user's global variables. On the other hand, if you know what you are doing you can touch a module's global variables with the same notation used to refer to its functions, ``modname.itemname``."

msgstr "هر ماژول فضای نام خصوصی خود را دارد که توسط تمام توابع تعریف‌شده در ماژول، به‌عنوان فضای نام سراسری استفاده می‌شود. بنابراین، نویسنده‌ی یک ماژول می‌تواند بدون نگرانی از تداخل تصادفی با متغیرهای سراسری کاربر، از متغیرهای سراسری درون ماژول استفاده کند. از طرف دیگر، اگر بدانید چه کاری انجام می‌دهید، می‌توانید با همان نگارشی که برای ارجاع به توابع ماژول استفاده می‌کنید، به متغیرهای سراسری ماژول دسترسی پیدا کنید: ``modname.itemname``."

msgid "Modules can import other modules. It is customary but not required to place all :keyword:`import` statements at the beginning of a module (or script, for that matter). The imported module names, if placed at the top level of a module (outside any functions or classes), are added to the module's global namespace."

msgstr "ماژول‌ها می‌توانند ماژول‌های دیگری را ایمپورت کنند. معمول است، اما اجباری نیست، که تمام دستورهای :keyword:`import` در ابتدای یک ماژول (یا به‌طور کلی یک اسکریپت) قرار داده شوند. نام ماژول‌های ایمپورت‌شده اگر در سطح بالای یک ماژول (خارج از هر تابع یا کلاس) قرار گرفته باشند، به فضای نام سراسری ماژول اضافه می‌شوند."

msgid "There is a variant of the :keyword:`import` statement that imports names from a module directly into the importing module's namespace. For example::"

msgstr "گونه‌ای از دستور :keyword:`import` وجود دارد که نام‌ها را از یک ماژول مستقیماً به فضای نام ماژولی که عمل ایمپورت کردن را انجام می‌دهد ایمپورت می‌کند. برای مثال::"

msgid ""

msgstr ""

msgid "This does not introduce the module name from which the imports are taken in the local namespace (so in the example, ``fibo`` is not defined)."

msgstr "این کار نام ماژولی را که ایمپورت کردن از آن انجام شده است، به فضای نام محلی اضافه نمی‌کند (بنابراین در مثال، ``fibo`` تعریف نشده است)."

msgid "There is even a variant to import all names that a module defines::"

msgstr "همچنین گونه‌ای وجود دارد که تمام نام‌هایی را که یک ماژول تعریف می‌کند ایمپورت می‌کند::"

msgid ""

msgstr ""

msgid "This imports all names except those beginning with an underscore (``_``). In most cases Python programmers do not use this facility since it introduces an unknown set of names into the interpreter, possibly hiding some things you have already defined."

msgstr "این دستور تمام نام‌ها را به‌جز نام‌هایی که با یک زیرخط (``_``) شروع می‌شوند ایمپورت می‌کند. در بیشتر موارد، برنامه‌نویسان پایتون از این قابلیت استفاده نمی‌کنند، زیرا مجموعه‌ای نامشخص از نام‌ها را وارد مفسر می‌کند و ممکن است برخی مواردی را که قبلاً تعریف کرده‌اید پنهان کند."

msgid "Note that in general the practice of importing ``*`` from a module or package is frowned upon, since it often causes poorly readable code. However, it is okay to use it to save typing in interactive sessions."

msgstr "توجه داشته باشید که به‌طور کلی، ایمپورت کردن ``*`` از یک ماژول یا بسته عملی نامطلوب محسوب می‌شود، زیرا اغلب باعث ایجاد کدی با خوانایی ضعیف می‌شود. بااین‌حال، استفاده از آن برای کاهش تایپ در نشست‌های تعاملی اشکالی ندارد."

msgid "If the module name is followed by :keyword:`!as`, then the name following :keyword:`!as` is bound directly to the imported module."

msgstr "اگر نام ماژول پس از :keyword:`!as` قرار گیرد، نامی که پس از :keyword:`!as` می‌آید مستقیماً به ماژول ایمپورت‌شده مقید می‌شود."

msgid ""

msgstr ""

msgid "This is effectively importing the module in the same way that ``import fibo`` will do, with the only difference of it being available as ``fib``."

msgstr "این کار در عمل همانند ایمپورت کردن ماژول به روشی که ``import fibo`` انجام می‌دهد است، با این تفاوت که ماژول به‌صورت ``fib`` در دسترس خواهد بود."

msgid "It can also be used when utilising :keyword:`from` with similar effects::"

msgstr "همچنین می‌توان هنگام استفاده از :keyword:`from` از آن با اثر مشابهی استفاده کرد::"

msgid ""

msgstr ""

msgid "For efficiency reasons, each module is only imported once per interpreter session. Therefore, if you change your modules, you must restart the interpreter -- or, if it's just one module you want to test interactively, use :func:`importlib.reload`, e.g. ``import importlib; importlib.reload(modulename)``."

msgstr "به دلایل کارایی، هر ماژول در هر نشست مفسر فقط یک بار ایمپورت می‌شود. بنابراین، اگر ماژول‌های خود را تغییر دهید، باید مفسر را دوباره راه‌اندازی کنید؛ یا اگر فقط یک ماژول را می‌خواهید به‌صورت تعاملی آزمایش کنید، از :func:`importlib.reload` استفاده کنید، برای مثال: ``import importlib; importlib.reload(modulename)``."

msgid "Executing modules as scripts"

msgstr "اجرای ماژول‌ها به‌عنوان اسکریپت"

msgid "When you run a Python module with ::"

msgstr "وقتی یک ماژول پایتون را با استفاده از این دستور اجرا می‌کنید ::"

msgid "python fibo.py <arguments>"

msgstr "python fibo.py <arguments>"

msgid "the code in the module will be executed, just as if you imported it, but with the ``__name__`` set to ``\"__main__\"``. That means that by adding this code at the end of your module::"

msgstr "کد موجود در ماژول اجرا خواهد شد، درست همانند زمانی که آن را ایمپورت کرده‌اید، اما مقدار ``__name__`` برابر با ``\"__main__\"`` تنظیم می‌شود. این یعنی با افزودن کد زیر در انتهای ماژول خود::"

msgid ""

msgstr ""

msgid "you can make the file usable as a script as well as an importable module, because the code that parses the command line only runs if the module is executed as the \"main\" file:"

msgstr "می‌توانید پرونده را هم به‌عنوان یک اسکریپت و هم به‌عنوان یک ماژول قابل ایمپورت کردن استفاده کنید، زیرا کدی که خط فرمان را تجزیه می‌کند فقط زمانی اجرا می‌شود که ماژول به‌عنوان پرونده «اصلی» اجرا شود:"

msgid ""

msgstr ""

msgid "If the module is imported, the code is not run::"

msgstr "اگر ماژول ایمپورت شود، کد اجرا نمی‌شود::"

msgid ""

msgstr ""

msgid "This is often used either to provide a convenient user interface to a module, or for testing purposes (running the module as a script executes a test suite)."

msgstr "این روش اغلب برای فراهم کردن یک رابط کاربری مناسب برای یک ماژول یا برای اهداف آزمایشی استفاده می‌شود (اجرای ماژول به‌عنوان یک اسکریپت باعث اجرای یک بدنه‌ی آزمون می‌شود)."

msgid "The Module Search Path"

msgstr "مسیر جست‌وجوی ماژول‌ها"

msgid "When a module named :mod:`!spam` is imported, the interpreter first searches for a built-in module with that name. These module names are listed in :data:`sys.builtin_module_names`. If not found, it then searches for a file named :file:`spam.py` in a list of directories given by the variable :data:`sys.path`. :data:`sys.path` is initialized from these locations:"

msgstr "هنگامی که یک ماژول با نام :mod:`!spam` ایمپورت می‌شود، مفسر ابتدا به دنبال یک ماژول توکار با همان نام می‌گردد. نام این ماژول‌ها در :data:`sys.builtin_module_names` فهرست شده‌اند. اگر یافت نشود، سپس به دنبال پرونده‌ای با نام :file:`spam.py` در فهرستی از پوشه‌ها می‌گردد که توسط متغیر :data:`sys.path` مشخص شده‌اند. :data:`sys.path` از این مکان‌ها مقداردهی اولیه می‌شود:"

msgid "The directory containing the input script (or the current directory when no file is specified)."

msgstr "پوشه‌ای که اسکریپت ورودی در آن قرار دارد (یا پوشه‌ی جاری، زمانی که هیچ پرونده‌ای مشخص نشده باشد)."

msgid ":envvar:`PYTHONPATH` (a list of directory names, with the same syntax as the shell variable :envvar:`PATH`)."

msgstr ":envvar:`PYTHONPATH` (فهرستی از نام پوشه‌ها با همان نحوی که متغیر پوسته‌ی :envvar:`PATH` دارد)."

msgid "The installation-dependent default (by convention including a ``site-packages`` directory, handled by the :mod:`site` module)."

msgstr "مقدار پیش‌فرض وابسته به نصب (که طبق قرارداد شامل یک پوشه‌ی ``site-packages`` است و توسط ماژول :mod:`site` مدیریت می‌شود)."

msgid "More details are at :ref:`sys-path-init`."

msgstr "جزئیات بیشتر در :ref:`sys-path-init` موجود است."

msgid "On file systems which support symlinks, the directory containing the input script is calculated after the symlink is followed. In other words the directory containing the symlink is **not** added to the module search path."

msgstr "در سیستم‌های پرونده‌ای که از پیوندهای نمادین پشتیبانی می‌کنند، پوشه‌ی شامل اسکریپت ورودی پس از دنبال کردن پیوند نمادین محاسبه می‌شود. به عبارت دیگر، پوشه‌ای که پیوند نمادین در آن قرار دارد **به مسیر جست‌وجوی ماژول‌ها اضافه نمی‌شود**."

msgid "After initialization, Python programs can modify :data:`sys.path`. The directory containing the script being run is placed at the beginning of the search path, ahead of the standard library path. This means that scripts in that directory will be loaded instead of modules of the same name in the library directory. This is an error unless the replacement is intended. See section :ref:`tut-standardmodules` for more information."

msgstr "پس از مقداردهی اولیه، برنامه‌های پایتون می‌توانند :data:`sys.path` را تغییر دهند. پوشه‌ای که اسکریپت در حال اجرا در آن قرار دارد، در ابتدای مسیر جست‌وجو و پیش از مسیر کتابخانه‌ی استاندارد قرار داده می‌شود. این بدان معناست که اسکریپت‌های موجود در آن پوشه، به‌جای ماژول‌هایی با همان نام در پوشه‌ی کتابخانه بارگذاری خواهند شد. این کار یک خطا محسوب می‌شود، مگر اینکه جایگزینی موردنظر باشد. برای اطلاعات بیشتر، بخش :ref:`tut-standardmodules` را ببینید."

msgid "\"Compiled\" Python files"

msgstr "پرونده‌های پایتون «کامپایل‌شده»"

msgid "To speed up loading modules, Python caches the compiled version of each module in the ``__pycache__`` directory under the name :file:`module.{version}.pyc`, where the version encodes the format of the compiled file; it generally contains the Python version number. For example, in CPython release 3.3 the compiled version of spam.py would be cached as ``__pycache__/spam.cpython-33.pyc``. This naming convention allows compiled modules from different releases and different versions of Python to coexist."

msgstr "برای افزایش سرعت بارگذاری ماژول‌ها، پایتون نسخه‌ی کامپایل‌شده‌ی هر ماژول را در پوشه‌ی ``__pycache__`` و با نام :file:`module.{version}.pyc` ذخیره می‌کند؛ در این نام، نسخه قالب پرونده کامپایل‌شده را مشخص می‌کند و معمولاً شامل شماره‌ی نسخه‌ی پایتون است. برای مثال، در انتشار CPython نسخه‌ی 3.3، نسخه‌ی کامپایل‌شده‌ی spam.py به‌صورت ``__pycache__/spam.cpython-33.pyc`` ذخیره می‌شود. این قرارداد نام‌گذاری اجازه می‌دهد ماژول‌های کامپایل‌شده از انتشارها و نسخه‌های مختلف پایتون در کنار یکدیگر وجود داشته باشند."

msgid "Python checks the modification date of the source against the compiled version to see if it's out of date and needs to be recompiled. This is a completely automatic process. Also, the compiled modules are platform-independent, so the same library can be shared among systems with different architectures."

msgstr "پایتون تاریخ تغییر پرونده منبع را با نسخه‌ی کامپایل‌شده بررسی می‌کند تا مشخص شود آیا قدیمی شده است و نیاز به کامپایل مجدد دارد یا خیر. این فرایند کاملاً خودکار است. همچنین، ماژول‌های کامپایل‌شده مستقل از پلتفرم هستند، بنابراین یک کتابخانه‌ی یکسان می‌تواند بین سیستم‌هایی با معماری‌های متفاوت به اشتراک گذاشته شود."

msgid "Python does not check the cache in two circumstances. First, it always recompiles and does not store the result for the module that's loaded directly from the command line. Second, it does not check the cache if there is no source module. To support a non-source (compiled only) distribution, the compiled module must be in the source directory, and there must not be a source module."

msgstr "پایتون در دو حالت، حافظه‌ی نهان را بررسی نمی‌کند. نخست، همیشه ماژولی را که مستقیماً از خط فرمان بارگذاری شده است دوباره کامپایل می‌کند و نتیجه را ذخیره نمی‌کند. دوم، اگر هیچ ماژول منبعی وجود نداشته باشد، حافظه‌ی نهان را بررسی نمی‌کند. برای پشتیبانی از توزیع‌های بدون منبع (فقط کامپایل‌شده)، ماژول کامپایل‌شده باید در پوشه‌ی منبع قرار داشته باشد و نباید ماژول منبعی وجود داشته باشد."

msgid "Some tips for experts:"

msgstr "چند نکته برای متخصصان:"

msgid "You can use the :option:`-O` or :option:`-OO` switches on the Python command to reduce the size of a compiled module. The ``-O`` switch removes assert statements, the ``-OO`` switch removes both assert statements and __doc__ strings. Since some programs may rely on having these available, you should only use this option if you know what you're doing. \"Optimized\" modules have an ``opt-`` tag and are usually smaller. Future releases may change the effects of optimization."

msgstr "می‌توانید از گزینه‌های :option:`-O` یا :option:`-OO` در دستور پایتون برای کاهش اندازه‌ی یک ماژول کامپایل‌شده استفاده کنید. گزینه‌ی ``-O`` دستورهای assert را حذف می‌کند و گزینه‌ی ``-OO`` هم دستورهای assert و هم رشته‌های **doc** را حذف می‌کند. از آنجا که برخی برنامه‌ها ممکن است به وجود این موارد وابسته باشند، فقط زمانی باید از این گزینه استفاده کنید که بدانید چه کاری انجام می‌دهید. ماژول‌های «بهینه‌شده» دارای برچسب ``opt-`` هستند و معمولاً کوچک‌ترند. انتشارهای آینده ممکن است اثرات بهینه‌سازی را تغییر دهند."

msgid "A program doesn't run any faster when it is read from a ``.pyc`` file than when it is read from a ``.py`` file; the only thing that's faster about ``.pyc`` files is the speed with which they are loaded."

msgstr "یک برنامه زمانی که از یک پرونده ``.pyc`` خوانده می‌شود، سریع‌تر از زمانی که از یک پرونده ``.py`` خوانده می‌شود اجرا نمی‌شود؛ تنها چیزی که در پرونده‌های ``.pyc`` سریع‌تر است، سرعت بارگذاری آن‌هاست."

msgid "The module :mod:`compileall` can create .pyc files for all modules in a directory."

msgstr "ماژول :mod:`compileall` می‌تواند برای تمام ماژول‌های موجود در یک پوشه پرونده‌های .pyc ایجاد کند."

msgid "There is more detail on this process, including a flow chart of the decisions, in :pep:`3147`."

msgstr "جزئیات بیشتری درباره‌ی این فرایند، از جمله نمودار جریان تصمیم‌ها، در :pep:`3147` آمده است."

msgid "Standard Modules"

msgstr "ماژول‌های استاندارد"

msgid "Python comes with a library of standard modules, described in a separate document, the Python Library Reference (\"Library Reference\" hereafter). Some modules are built into the interpreter; these provide access to operations that are not part of the core of the language but are nevertheless built in, either for efficiency or to provide access to operating system primitives such as system calls. The set of such modules is a configuration option which also depends on the underlying platform. For example, the :mod:`winreg` module is only provided on Windows systems. One particular module deserves some attention: :mod:`sys`, which is built into every Python interpreter. The variables ``sys.ps1`` and ``sys.ps2`` define the strings used as primary and secondary prompts::"

msgstr "پایتون همراه با مجموعه‌ای از ماژول‌های استاندارد ارائه می‌شود که در یک سند جداگانه، یعنی مرجع کتابخانه‌ی پایتون (\"مرجع کتابخانه\" از اینجا به بعد)، توضیح داده شده‌اند. برخی ماژول‌ها در مفسر توکار هستند؛ این ماژول‌ها دسترسی به عملیاتی را فراهم می‌کنند که بخشی از هسته‌ی زبان نیستند، اما بااین‌حال، یا برای افزایش کارایی یا برای فراهم کردن دسترسی به امکانات سیستم‌عامل مانند فراخوانی‌های سیستمی، به‌صورت توکار وجود دارند. مجموعه‌ی این ماژول‌ها یک گزینه‌ی پیکربندی است که به پلتفرم زیربنایی نیز وابسته است. برای مثال، ماژول :mod:`winreg` فقط در سیستم‌های ویندوز ارائه می‌شود. یک ماژول خاص شایسته‌ی توجه بیشتر است: :mod:`sys` که در هر مفسر پایتون توکار است. متغیرهای ``sys.ps1`` و ``sys.ps2`` رشته‌هایی را تعریف می‌کنند که به‌عنوان اعلان‌های اصلی و ثانویه استفاده می‌شوند::"

msgid ""

msgstr ""

msgid "These two variables are only defined if the interpreter is in interactive mode."

msgstr "این دو متغیر فقط زمانی تعریف می‌شوند که مفسر در حالت تعاملی باشد."

msgid "The variable ``sys.path`` is a list of strings that determines the interpreter's search path for modules. It is initialized to a default path taken from the environment variable :envvar:`PYTHONPATH`, or from a built-in default if :envvar:`PYTHONPATH` is not set. You can modify it using standard list operations::"

msgstr "متغیر ``sys.path`` فهرستی از رشته‌هاست که مسیر جست‌وجوی مفسر برای ماژول‌ها را تعیین می‌کند. این متغیر از یک مسیر پیش‌فرض گرفته‌شده از متغیر محیطی :envvar:`PYTHONPATH` مقداردهی اولیه می‌شود، یا اگر :envvar:`PYTHONPATH` تنظیم نشده باشد، از یک مقدار پیش‌فرض توکار استفاده می‌کند. می‌توانید آن را با استفاده از عملیات استاندارد فهرست‌ها تغییر دهید::"

msgid ""

msgstr ""

msgid "The :func:`dir` Function"

msgstr "تابع :func:`dir`"

msgid "The built-in function :func:`dir` is used to find out which names a module defines. It returns a sorted list of strings::"

msgstr "تابع توکار :func:`dir` برای یافتن نام‌هایی که یک ماژول تعریف می‌کند استفاده می‌شود. این تابع یک فهرست مرتب‌شده از رشته‌ها برمی‌گرداند::"

msgid ""

msgstr ""

msgid "Without arguments, :func:`dir` lists the names you have defined currently::"

msgstr "بدون آرگومان، :func:`dir` نام‌هایی را که در حال حاضر تعریف کرده‌اید فهرست می‌کند::"

msgid ""

msgstr ""

msgid "Note that it lists all types of names: variables, modules, functions, etc."

msgstr "توجه کنید که این تابع همه‌ی انواع نام‌ها را فهرست می‌کند: متغیرها، ماژول‌ها، توابع و غیره."

msgid ":func:`dir` does not list the names of built-in functions and variables. If you want a list of those, they are defined in the standard module :mod:`builtins`::"

msgstr ":func:`dir` نام توابع و متغیرهای توکار را فهرست نمی‌کند. اگر فهرستی از آن‌ها می‌خواهید، این موارد در ماژول استاندارد :mod:`builtins` تعریف شده‌اند::"

msgid ""

msgstr ""

msgid "Packages"

msgstr "بسته‌ها"

msgid "Packages are a way of structuring Python's module namespace by using \"dotted module names\". For example, the module name :mod:`!A.B` designates a submodule named ``B`` in a package named ``A``. Just like the use of modules saves the authors of different modules from having to worry about each other's global variable names, the use of dotted module names saves the authors of multi-module packages like NumPy or Pillow from having to worry about each other's module names."

msgstr "بسته‌ها روشی برای ساختاربندی فضای نام ماژول‌های پایتون با استفاده از «نام‌های نقطه‌دار ماژول» هستند. برای مثال، نام ماژول :mod:`!A.B` یک زیرماژول با نام ``B`` در بسته‌ای با نام ``A`` را مشخص می‌کند. همان‌طور که استفاده از ماژول‌ها باعث می‌شود نویسندگان ماژول‌های مختلف نگران نام متغیرهای سراسری یکدیگر نباشند، استفاده از نام‌های نقطه‌دار ماژول نیز باعث می‌شود نویسندگان بسته‌های چندماژوله‌ای مانند NumPy یا Pillow نگران نام ماژول‌های یکدیگر نباشند."

msgid "Suppose you want to design a collection of modules (a \"package\") for the uniform handling of sound files and sound data. There are many different sound file formats (usually recognized by their extension, for example: :file:`.wav`, :file:`.aiff`, :file:`.au`), so you may need to create and maintain a growing collection of modules for the conversion between the various file formats. There are also many different operations you might want to perform on sound data (such as mixing, adding echo, applying an equalizer function, creating an artificial stereo effect), so in addition you will be writing a never-ending stream of modules to perform these operations. Here's a possible structure for your package (expressed in terms of a hierarchical filesystem):"

msgstr "فرض کنید می‌خواهید مجموعه‌ای از ماژول‌ها (یک «بسته») را برای مدیریت یکپارچه‌ی پرونده‌های صوتی و داده‌های صوتی طراحی کنید. قالب‌های پرونده صوتی بسیار متفاوتی وجود دارند (که معمولاً با پسوندشان شناخته می‌شوند، برای مثال: :file:`.wav`، :file:`.aiff`، :file:`.au`)؛ بنابراین ممکن است نیاز داشته باشید مجموعه‌ای در حال رشد از ماژول‌ها را برای تبدیل بین قالب‌های مختلف پرونده ایجاد و نگهداری کنید. همچنین عملیات‌های مختلف بسیاری وجود دارند که ممکن است بخواهید روی داده‌های صوتی انجام دهید (مانند ترکیب کردن، افزودن پژواک، اعمال تابع اکولایزر، ایجاد یک اثر استریوی مصنوعی)، بنابراین علاوه بر این، جریان بی‌پایانی از ماژول‌ها برای انجام این عملیات‌ها خواهید نوشت. ساختار احتمالی زیر برای بسته‌ی شما وجود دارد (که به‌صورت یک سامانه فایل‌بندی سلسله‌مراتبی بیان شده است):"

msgid ""

msgstr ""

msgid "When importing the package, Python searches through the directories on ``sys.path`` looking for the package subdirectory."

msgstr "هنگام ایمپورت کردن بسته، پایتون پوشه‌های موجود در ``sys.path`` را جست‌وجو می‌کند تا زیرپوشه‌ی بسته را پیدا کند."

msgid "The :file:`__init__.py` files are required to make Python treat directories containing the file as packages (unless using a :term:`namespace package`, a relatively advanced feature). This prevents directories with a common name, such as ``string``, from unintentionally hiding valid modules that occur later on the module search path. In the simplest case, :file:`__init__.py` can just be an empty file, but it can also execute initialization code for the package or set the ``__all__`` variable, described later."

msgstr "پرونده‌های :file:`__init__.py` لازم هستند تا پایتون پوشه‌هایی را که شامل این پرونده هستند به‌عنوان بسته در نظر بگیرد (مگر اینکه از یک :term:`namespace package` استفاده شود که قابلیتی نسبتاً پیشرفته است). این کار از پنهان شدن ناخواسته‌ی ماژول‌های معتبر که بعداً در مسیر جست‌وجوی ماژول قرار دارند، توسط پوشه‌هایی با نام مشترک مانند ``string`` جلوگیری می‌کند. در ساده‌ترین حالت، :file:`__init__.py` می‌تواند فقط یک پرونده خالی باشد، اما می‌تواند کد مقداردهی اولیه‌ی بسته را نیز اجرا کند یا متغیر ``__all__`` را که بعداً توضیح داده می‌شود، تنظیم کند."

msgid "Users of the package can import individual modules from the package, for example::"

msgstr "کاربران بسته می‌توانند ماژول‌های جداگانه‌ای را از بسته ایمپورت کنند، برای مثال::"

msgid "import sound.effects.echo"

msgstr "import sound.effects.echo"

msgid "This loads the submodule :mod:`!sound.effects.echo`. It must be referenced with its full name. ::"

msgstr "این کار زیرماژول :mod:`!sound.effects.echo` را بارگذاری می‌کند. این ماژول باید با نام کامل خود ارجاع داده شود. ::"

msgid "sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)"

msgstr "sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)"

msgid "An alternative way of importing the submodule is::"

msgstr "روش جایگزین برای ایمپورت کردن زیرماژول به شکل زیر است::"

msgid "from sound.effects import echo"

msgstr "from sound.effects import echo"

msgid "This also loads the submodule :mod:`!echo`, and makes it available without its package prefix, so it can be used as follows::"

msgstr "این روش نیز زیرماژول :mod:`!echo` را بارگذاری می‌کند و آن را بدون پیشوند بسته در دسترس قرار می‌دهد، بنابراین می‌توان از آن به شکل زیر استفاده کرد::"

msgid "echo.echofilter(input, output, delay=0.7, atten=4)"

msgstr "echo.echofilter(input, output, delay=0.7, atten=4)"

msgid "Yet another variation is to import the desired function or variable directly::"

msgstr "یک حالت دیگر، ایمپورت کردن مستقیم تابع یا متغیر موردنظر است::"

msgid "from sound.effects.echo import echofilter"

msgstr "from sound.effects.echo import echofilter"

msgid "Again, this loads the submodule :mod:`!echo`, but this makes its function :func:`!echofilter` directly available::"

msgstr "دوباره، این کار زیرماژول :mod:`!echo` را بارگذاری می‌کند، اما باعث می‌شود تابع آن، یعنی :func:`!echofilter`، مستقیماً در دسترس باشد::"

msgid "echofilter(input, output, delay=0.7, atten=4)"

msgstr "echofilter(input, output, delay=0.7, atten=4)"

msgid "Note that when using ``from package import item``, the item can be either a submodule (or subpackage) of the package, or some other name defined in the package, like a function, class or variable. The ``import`` statement first tests whether the item is defined in the package; if not, it assumes it is a module and attempts to load it. If it fails to find it, an :exc:`ImportError` exception is raised."

msgstr "توجه کنید که هنگام استفاده از ``from package import item``، مورد item می‌تواند یک زیرماژول (یا زیربسته) از بسته باشد، یا نام دیگری باشد که در بسته تعریف شده است، مانند یک تابع، کلاس یا متغیر. دستور ``import`` ابتدا بررسی می‌کند که آیا item در بسته تعریف شده است یا خیر؛ اگر تعریف نشده باشد، فرض می‌کند که یک ماژول است و تلاش می‌کند آن را بارگذاری کند. اگر نتواند آن را پیدا کند، یک استثنای :exc:`ImportError` پرتاب می‌شود."

msgid "Contrarily, when using syntax like ``import item.subitem.subsubitem``, each item except for the last must be a package; the last item can be a module or a package but can't be a class or function or variable defined in the previous item."

msgstr "برعکس، هنگام استفاده از نحوی مانند ``import item.subitem.subsubitem``، هر مورد به‌جز آخرین مورد باید یک بسته باشد؛ آخرین مورد می‌تواند یک ماژول یا یک بسته باشد، اما نمی‌تواند یک کلاس، تابع یا متغیر تعریف‌شده در مورد قبلی باشد."

msgid "Importing \\* From a Package"

msgstr "ایمپورت کردن \\* از یک بسته"

msgid "Now what happens when the user writes ``from sound.effects import *``? Ideally, one would hope that this somehow goes out to the filesystem, finds which submodules are present in the package, and imports them all. This could take a long time and importing sub-modules might have unwanted side-effects that should only happen when the sub-module is explicitly imported."

msgstr "اکنون اگر کاربر بنویسد ``from sound.effects import *`` چه اتفاقی می‌افتد؟ در حالت ایده‌آل، انتظار می‌رود این دستور به‌نحوی به سامانه فایل‌بندی مراجعه کند، زیرماژول‌های موجود در بسته را پیدا کند و همه‌ی آن‌ها را ایمپورت کند. این کار می‌تواند زمان زیادی طول بکشد و ایمپورت کردن زیرماژول‌ها ممکن است عوارض جانبی ناخواسته‌ای پرتاب کند که باید فقط هنگام ایمپورت کردن صریح زیرماژول رخ دهند."

msgid "The only solution is for the package author to provide an explicit index of the package. The :keyword:`import` statement uses the following convention: if a package's :file:`__init__.py` code defines a list named ``__all__``, it is taken to be the list of module names that should be imported when ``from package import *`` is encountered. It is up to the package author to keep this list up-to-date when a new version of the package is released. Package authors may also decide not to support it, if they don't see a use for importing \\* from their package. For example, the file :file:`sound/effects/__init__.py` could contain the following code::"

msgstr "تنها راه‌حل این است که نویسنده‌ی بسته یک فهرست صریح از بسته فراهم کند. دستور :keyword:`import` از قرارداد زیر استفاده می‌کند: اگر کد :file:`__init__.py` یک بسته، فهرستی با نام ``__all__`` تعریف کند، این فهرست به‌عنوان فهرست نام ماژول‌هایی در نظر گرفته می‌شود که هنگام مشاهده‌ی ``from package import *`` باید ایمپورت شوند. این وظیفه‌ی نویسنده‌ی بسته است که هنگام انتشار نسخه‌ی جدید بسته، این فهرست را به‌روز نگه دارد. نویسندگان بسته همچنین ممکن است تصمیم بگیرند از این قابلیت پشتیبانی نکنند، اگر کاربردی برای ایمپورت کردن \\* از بسته‌ی خود نمی‌بینند. برای مثال، پرونده :file:`sound/effects/__init__.py` می‌تواند شامل کد زیر باشد::"

msgid "__all__ = [\"echo\", \"surround\", \"reverse\"]"

msgstr "__all__ = [\"echo\", \"surround\", \"reverse\"]"

msgid "This would mean that ``from sound.effects import *`` would import the three named submodules of the :mod:`!sound.effects` package."

msgstr "این یعنی ``from sound.effects import *`` سه زیرماژول نام‌برده‌ی بسته‌ی :mod:`!sound.effects` را ایمپورت خواهد کرد."

msgid "Be aware that submodules might become shadowed by locally defined names. For example, if you added a ``reverse`` function to the :file:`sound/effects/__init__.py` file, the ``from sound.effects import *`` would only import the two submodules ``echo`` and ``surround``, but *not* the ``reverse`` submodule, because it is shadowed by the locally defined ``reverse`` function::"

msgstr "توجه داشته باشید که زیرماژول‌ها ممکن است توسط نام‌هایی که به‌صورت محلی تعریف شده‌اند، پوشانده شوند. برای مثال، اگر یک تابع ``reverse`` به پرونده :file:`sound/effects/__init__.py` اضافه کنید، دستور ``from sound.effects import *`` فقط دو زیرماژول ``echo`` و ``surround`` را ایمپورت خواهد کرد، اما *زیرماژول* ``reverse`` را ایمپورت نمی‌کند، زیرا توسط تابع ``reverse`` تعریف‌شده در همان فضا پوشانده شده است::"

msgid ""

msgstr ""

msgid "If ``__all__`` is not defined, the statement ``from sound.effects import *`` does *not* import all submodules from the package :mod:`!sound.effects` into the current namespace; it only ensures that the package :mod:`!sound.effects` has been imported (possibly running any initialization code in :file:`__init__.py`) and then imports whatever names are defined in the package. This includes any names defined (and submodules explicitly loaded) by :file:`__init__.py`. It also includes any submodules of the package that were explicitly loaded by previous :keyword:`import` statements. Consider this code::"

msgstr "اگر ``__all__`` تعریف نشده باشد، دستور ``from sound.effects import *`` تمام زیرماژول‌های بسته‌ی :mod:`!sound.effects` را به فضای نام فعلی ایمپورت *نمی‌کند*؛ این دستور فقط اطمینان حاصل می‌کند که بسته‌ی :mod:`!sound.effects` ایمپورت شده است (و احتمالاً هر کد مقداردهی اولیه‌ای در :file:`__init__.py` اجرا می‌شود) و سپس هر نامی را که در بسته تعریف شده است ایمپورت می‌کند. این شامل هر نامی است که توسط :file:`__init__.py` تعریف شده (و زیرماژول‌هایی که به‌صورت صریح بارگذاری شده‌اند) نیز می‌شود. همچنین شامل هر زیرماژول بسته‌ای است که قبلاً توسط دستورهای :keyword:`import` به‌صورت صریح بارگذاری شده‌اند. این کد را در نظر بگیرید::"

msgid ""

msgstr ""

msgid "In this example, the :mod:`!echo` and :mod:`!surround` modules are imported in the current namespace because they are defined in the :mod:`!sound.effects` package when the ``from...import`` statement is executed. (This also works when ``__all__`` is defined.)"

msgstr "در این مثال، ماژول‌های :mod:`!echo` و :mod:`!surround` در فضای نام فعلی ایمپورت می‌شوند، زیرا هنگام اجرای دستور ``from...import`` در بسته‌ی :mod:`!sound.effects` تعریف شده‌اند. (این حالت زمانی که ``__all__`` تعریف شده باشد نیز کار می‌کند.)"

msgid "Although certain modules are designed to export only names that follow certain patterns when you use ``import *``, it is still considered bad practice in production code."

msgstr "اگرچه برخی ماژول‌ها طوری طراحی شده‌اند که هنگام استفاده از ``import *`` فقط نام‌هایی مطابق با الگوهای خاص اکسپورت کنند، همچنان این کار در کدهای تولیدی روشی نامناسب محسوب می‌شود."

msgid "Remember, there is nothing wrong with using ``from package import specific_submodule``! In fact, this is the recommended notation unless the importing module needs to use submodules with the same name from different packages."

msgstr "به یاد داشته باشید که استفاده از ``from package import specific_submodule`` هیچ مشکلی ندارد! در واقع، این نمادگذاری توصیه‌شده است، مگر اینکه ماژول ایمپورت‌کننده نیاز داشته باشد از زیرماژول‌هایی با نام یکسان از بسته‌های مختلف استفاده کند."

msgid "Intra-package References"

msgstr "ارجاع‌های درون‌بسته‌ای"

msgid "When packages are structured into subpackages (as with the :mod:`!sound` package in the example), you can use absolute imports to refer to submodules of siblings packages. For example, if the module :mod:`!sound.filters.vocoder` needs to use the :mod:`!echo` module in the :mod:`!sound.effects` package, it can use ``from sound.effects import echo``."

msgstr "هنگامی که بسته‌ها به زیربسته‌ها ساختاربندی می‌شوند (مانند بسته‌ی :mod:`!sound` در مثال)، می‌توانید از ایمپورت کردن مطلق برای ارجاع به زیرماژول‌های بسته‌های هم‌سطح استفاده کنید. برای مثال، اگر ماژول :mod:`!sound.filters.vocoder` نیاز داشته باشد از ماژول :mod:`!echo` در بسته‌ی :mod:`!sound.effects` استفاده کند، می‌تواند از ``from sound.effects import echo`` استفاده کند."

msgid "You can also write relative imports, with the ``from module import name`` form of import statement. These imports use leading dots to indicate the current and parent packages involved in the relative import. From the :mod:`!surround` module for example, you might use::"

msgstr "همچنین می‌توانید از ایمپورت نسبی استفاده کنید، به شکل ``from module import name`` در دستور import. این ایمپورت‌ها از نقطه‌های ابتدایی برای مشخص کردن بسته‌ی فعلی و بسته‌های والد درگیر در ایمپورت نسبی استفاده می‌کنند. برای مثال، از داخل ماژول :mod:`!surround` می‌توانید از دستور زیر استفاده کنید::"

msgid ""

msgstr ""

msgid "Note that relative imports are based on the name of the current module's package. Since the main module does not have a package, modules intended for use as the main module of a Python application must always use absolute imports."

msgstr "توجه کنید که ایمپورت کردن‌های نسبی بر اساس نام بسته‌ی ماژول فعلی هستند. از آنجا که ماژول اصلی هیچ بسته‌ای ندارد، ماژول‌هایی که قرار است به‌عنوان ماژول اصلی یک برنامه‌ی پایتون استفاده شوند، باید همیشه از ایمپورت کردن‌های مطلق استفاده کنند."

msgid "Footnotes"

msgstr "پانویس‌ها"

msgid "In fact function definitions are also 'statements' that are 'executed'; the execution of a module-level function definition adds the function name to the module's global namespace."

msgstr "در واقع، تعریف توابع نیز «دستورهایی» هستند که «اجرا» می‌شوند؛ اجرای یک تعریف تابع در سطح ماژول، نام تابع را به فضای نام سراسری ماژول اضافه می‌کند."

msgid "module"

msgstr "ماژول"

msgid "search"

msgstr "جست‌وجو"

msgid "path"

msgstr "مسیر"

msgid "sys"

msgstr "sys"

msgid "builtins"

msgstr "builtins"

msgid "__all__"

msgstr "__all__"