edited l03, part 1

Author: Saeid Darvish

source/index.rst

@@ -30,7 +30,7 @@
    preface
    lessons/l01-introduction-to-python
    lessons/l02-setup-python
-   lessons/l03
+   lessons/l03-create-and-run-a-python-project
    lessons/l04
    lessons/l05
    lessons/l06

source/lessons/l03.rst …/l03-create-and-run-a-python-project.rstsource/lessons/l03.rst renamed to source/lessons/l03-create-and-run-a-python-project.rst source/lessons/l03.rst renamed to source/lessons/l03-create-and-run-a-python-project.rst

@@ -1,10 +1,12 @@
 .. role:: emoji-size
 
 .. meta::
-   :description: کتاب آنلاین و آزاد آموزش زبان برنامه‌نویسی پایتون به فارسی - درس سوم ایجاد و اجرای پروژه از پایتون
+   :description: پایتون به فارسی - کتاب آنلاین و آزاد آموزش زبان برنامه‌نویسی پایتون - درس سوم: چگونگی ایجاد و اجرای یک پروژه پایتون
    :keywords: پایتون,آموزش پایتون, آموزش برنامه نویسی, ایجاد پروژه پایتون, اسکریپت پایتون, ماژول پایتون, بسته پایتون, ساختار پایتون, پروژه پایتون, سورس کد, سورس کد پایتون, اجرای پایتون, اسکریپت, ماژول, pyvenv, virtualenv
 
 
+.. _lesson-03: 
+
 درس ۰۳: چگونگی ایجاد و اجرای یک پروژه پایتون
 =============================================
 
@@ -27,26 +29,27 @@
 
 ----
 
+.. _project-structure: 
+
 ساختار پروژه
 --------------
-نخستین گام در توسعه‌ یک برنامه پایتون ایجاد یک پروژه است که پس از آن نوشتن کدها یا ایجاد سورس کد (`Source code <https://en.wikipedia.org/wiki/Source_code>`_) برنامه آغاز می‌شود.
 
 سورس کد یک پروژه به زبان پایتون در قالب یک یا چند «ماژول» (Module) توسعه می‌یابد که در سورس کدهایی با بیش از یک ماژول بهتر است ماژول‌هایی که از نظر منطقی با یکدیگر مرتبط هستند را درون دایرکتوری‌هایی مجزا قرار دهیم که به این نوع دایرکتوری‌ها در زبان پایتون «بسته» (Package) گفته می‌شود.
 
 .. tip::
     یک یا چند ماژول درون یک دایرکتوری مشخص تشکیل یک بسته را می‌دهند و هر بسته خود می‌تواند حاوی بسته‌(های) دیگری باشد. 
 
 .. note::
-    از نسخه 3.3 پایتون با افزوده شدن ویژگی جدیدی به نام «بسته فضانام» (Namespace Package - `PEP 420 <http://www.python.org/dev/peps/pep-0420>`_)، تعریف بسته پایتون به دو شاخه «بسته عادی» (Regular Package) که همان تعریف قدیمی از بسته می‌باشد و بسته فضانام گسترش یافته است. [در درس مربوط به ماژول‌ها بیشتر توضیح داده خواهد شد]
+    از نسخه 3.3 پایتون با افزوده شدن ویژگی جدیدی به نام «بسته فضانام» (Namespace Package - `PEP 420 <http://www.python.org/dev/peps/pep-0420>`_)، تعریف بسته پایتون به دو شاخه «بسته عادی» (Regular Package) که همان تعریف قدیمی از بسته می‌باشد و بسته فضانام گسترش یافته است. در انتهای این درس به تفاوت این دو بسته پرداخته خواهد شد.
 
 در تعریف زبان پایتون دو نوع ماژول وجود دارد:
 
-۱- Pure Module (ماژول ناب)، همان تعریف عادی از ماژول پایتون است؛ فایل‌هایی با پسوند py که کد (تعاریف و دستورات) پایتون در آن‌ها نوشته می‌شوند.
+۱- Pure Module (ماژول عادی)، همان تعریف عادی از ماژول پایتون است؛ فایل‌هایی با پسوند py که کد (تعاریف و دستورات) پایتون در آن‌ها نوشته می‌شوند.
 
-۲- Extension Module (ماژول توسعه)، ماژول‌هایی که توسط زبان‌های برنامه‌نویسی دیگری  به غیر از پایتون  ایجاد شده‌اند. از درس یکم به خاطر داریم که پایتون یک زبان توسعه‌پذیر است و در کنار آن می‌توان از کد‌های نوشته شده با دیگر زبان‌های برنامه‌نویسی استفاده نمود: به مانند C و ++C در پیاده‌سازی CPython یا Java در پیاده‌سازی Jython یا #C در پیاده‌سازی IronPython - [ایجاد و استفاده از این نوع ماژول در درسی جداگانه بررسی خواهد شد.]
+۲- Extension Module (ماژول توسعه)، ماژول‌هایی که توسط زبان‌های برنامه‌نویسی دیگری  به غیر از پایتون  ایجاد شده‌اند. از درس یکم به خاطر داریم که پایتون یک زبان توسعه‌پذیر است و در کنار آن می‌توان از کد‌های نوشته شده با دیگر زبان‌های برنامه‌نویسی استفاده نمود: به مانند C و ++C در پیاده‌سازی CPython یا Java در پیاده‌سازی Jython یا #C در پیاده‌سازی IronPython - بررسی این نوع ماژول خارج از حوزه این کتاب است. در صورت علاقه برای مطالعه بیشتر می‌توانید به مستندات پایتون مراجعه (`Python/C API Reference <https://docs.python.org/3/c-api/index.html>`_) یا کتاب Python 3.6 Extending and Embedding Python نوشته Guido Van Rossum را تهیه نمایید.
 
 .. note::
-    از این پس هر جایی از کتاب که گفته شود «ماژول» منظور Pure Module خواهد بود، مگر اینکه نام «ماژول توسعه» به صراحت ذکر گردد.
+    از این پس هر جایی از این کتاب که گفته شود «ماژول» منظور Pure Module خواهد بود، مگر اینکه نام «ماژول توسعه» به صراحت ذکر گردد.
 
 در ایجاد یک پروژه از پایتون هیچ اجباری به رعایت ساختار خاصی نیست و حتی سورس کد یک پروژه می‌تواند تنها شامل یک ماژول باشد. به عنوان نمونه، شمای پایین از پروژه فرضی SampleProject را در نظر بگیرید:
 
@@ -62,66 +65,45 @@
         └── module_three.py
 
 .. tip::
-    در پایتون هر بسته‌ (عادی) می‌بایست حاوی فایل ویژه‌‌‌ init\_\_.py_\_\  باشد که البته الزامی به کدنویسی درون این فایل وجود ندارد. این فایل دایرکتوری خود را به عنوان یک بسته (محلی برای یافتن ماژول‌ها) به مفسر پایتون معرفی می‌کند.
+    در پایتون هر **بسته‌ عادی** می‌بایست حاوی فایل ویژه‌‌‌ init\_\_.py_\_\  باشد که البته الزامی به کدنویسی درون این فایل وجود ندارد. این فایل دایرکتوری خود را به عنوان یک بسته (محلی برای یافتن ماژول‌های مرتبط) به مفسر پایتون معرفی می‌کند.
 
 در ایجاد سورس کد باید به صورتی عمل شود که با اجرای یک ماژول‌ مشخص تمام برنامه اجرا گردد. این ماژول معمولا هم نام پروژه در نظر گرفته و با عنوان «اسکریپت» (Script) از آن یاد می‌شود (اینجا:‌ sample_project.py). در واقع اسکریپت، ماژولی است که با هدف اجرای برنامه توسعه می‌یابد و ایجاد سورس کد نیز از آن شروع می‌گردد. از طرفی همانطور که می‌دانیم یکی از ویژگی‌های پایتون امکان برنامه نویسی ماژولار (`Modular <http://en.wikipedia.org/wiki/Modular_programming>`_) است به این صورت که می‌توان کد‌های خود را بر حسب نیاز در ماژول‌هایی جداگانه نوشت و با وارد کردن (Import) آن‌ها در اسکریپت (یا ماژول‌های دیگر) از کد درون آن‌ها استفاده نمود. با این منطق می‌شود سورس کد یک پروژه از پایتون را تنها شامل یک اسکریپت تصور کرد که می‌تواند توسط تعدادی ماژول گسترش یابد؛ البته ممکن است ماژول‌ها نیز بر حسب نیاز در بسته‌هایی جداگانه قرار گرفته باشند.
 
 .. tip::
     [`PEP 8 <http://www.python.org/dev/peps/pep-0008/>`_]: در نام‌گذاری ماژول‌ها تنها از حروف کوچک استفاده می‌شود و در صورت نیاز می‌توان از کاراکتر خط زیرین (``_``) نیز استفاده نمود. نام بسته‌ها کوتاه بوده و از حروف کوچک تشکیل می‌گردد؛ استفاده از ``_`` در نام بسته پیشنهاد نمی‌شود.
 
-اکنون اطلاعات کافی برای شروع یک پروژه از پایتون را دارید ولی چنانچه می‌خواهید با ساختار مناسب پروژه‌ای که قرار است برای استفاده افراد دیگر از طریق PyPI یا سرویس‌هایی نظیر github.com منتشر شود (مانند یک کتابخانه کاربردی) آشنا شوید، ادامه این بخش را نیز مطالعه نمایید. در غیر این صورت می‌توانید به بخش بعدی از همین درس `پرش <#id7>`_ نمایید.
+اکنون اطلاعات کافی برای شروع یک پروژه از پایتون را دارید ولی چنانچه می‌خواهید با ساختار مناسب پروژه‌ای که قرار است برای استفاده افراد دیگر از طریق PyPI یا سرویس‌هایی نظیر github.com منتشر شود (مانند یک کتابخانه کاربردی) آشنا شوید، ادامه این بخش را نیز مطالعه نمایید. در غیر این صورت می‌توانید به بخش بعدی از همین درس `پرش <#source-code>`_ نمایید.
 
 جدا از سورس کد لازم است موارد دیگری نیز در ساختار این نوع پروژه‌ها در نظر گرفته شود؛ به ساختار پایین توجه نمایید:
 
 
 .. code::
     
-    SampleProject
+    my_project
     .
-    ├── docs/
+    ├── pyproject.toml
+    │
     ├── LICENSE.txt
-    ├── MANIFEST.in
     ├── README.rst
     ├── requirements.txt
-    ├── sampleproject/
-    │   ├── __init__.py
-    │   ├── module_one.py
-    │   ├── pakage/
-    │   │   ├── __init__.py
-    │   │   ├── module_two.py
-    │   │   └── module_three.py
-    │   ├── sample_project.py
-    │   └── test/
-    ├── setup.cfg
-    └── setup.py
-
-ساختار ابتدایی تنها شامل سورس کد می‌بود ولی در این ساختار تمام سورس کد در قالب یک بسته پایتون بخشی از مجموعه بزرگتری است که در آن یک سری فایل به مانند requirements.txt ،README.rst و setup.py به همراه دو دایرکتوری docs و test افزوده شده است. 
-در ادامه کمی از کاربرد این موارد توضیح داده می‌شود ولی تاکید می‌شود که در حال حاضر نیازی به رعایت این ساختار نیست و در انتهای کتاب با ایجاد یک پروژه عملی و قرار دادن آن بر روی github.com و PyPI به صورت کاربردی با آن‌ها آشنا خواهید شد. [برای کسب اطلاعات بیشتر می‌توانید از `اسناد پایتون <http://packaging.python.org/en/latest/distributing.html>`_ استفاده نمایید]
-
-**setup.py**: این فایل مهم دو کارکرد دارد: 
-۱- پیکربندی پروژه که از طریق آرگومان‌های تابع آماده ``()setup`` درون این فایل صورت می‌پذیرد.
-۲- یک رابط خط فرمان برای اجرای دستورات کاربردی مرتبط با پروژه (الگویی مشابه: ``<python setup.py <commands``). 
-
-  فهرست این دستورات از طریق وارد کردن دستوری مشابه ``python setup.py --help-commands`` قابل مشاهده است.
-
-**setup.cfg**: ساختاری شبیه به یک `فایل ini <http://en.wikipedia.org/wiki/INI_file>`_ داشته و در صورت نیاز گزینه‌های مربوط به دستورات خط فرمان setup.py در این فایل تعریف می‌گردند. برای مشاهده فهرست گزینه‌های یک دستور مشخص  می‌توانید از الگوی ``<python setup.py --help <commands`` پیروی نمایید. 
-
-**README.rst**: تمام پروژه‌ها می‌بایست شامل سندی برای توصیف خود باشند. در پایتون برای ایجاد اسناد معمولا از زبان نشانه‌گذاری `reStructuredText <http://en.wikipedia.org/wiki/ReStructuredText>`_ استفاده می‌گردد و به همین دلیل این اسناد پسوند rst دارند که البته اجباری به این مورد نیست و می‌توانید برای ایجاد این فایل از `Markdown <http://en.wikipedia.org/wiki/Markdown>`_ (پسوند md) نیز استفاده نمایید.
-
-**MANIFEST.in**: معمولا از این فایل برای معرفی فایل‌های غیر پایتونی موجود در پروژه استفاده می‌شود. زمانی که قصد ایجاد «سورس توزیع» یا sdist از پروژه را داشته باشید (دستوری مشابه: ``python setup.py sdist``)  تنها `فایل‌های مشخصی <http://docs.python.org/3.4/distutils/sourcedist.html#specifying-the-files-to-distribute>`_ از پروژه شناسایی می‌شوند و شناساندن باقی فایل‌ها (در صورت وجود) می‌بایست توسط این فایل (البته با `الگویی خاص <http://docs.python.org/2/distutils/sourcedist.html#the-manifest-in-template>`_) انجام گیرد.
+    │
+    ├── src/
+    │   └── unique_pakage_name/
+    │       ├── __init__.py
+    │       └── main.py
+    │   
+    ├── docs/
+    └── test/
 
-**requirements.txt**: از این فایل برای معرفی کتابخانه‌های خاصی که در پروژه استفاده شده‌اند و در زمان نصب یا اجرای سورس کد، وجود یا نصب بودن آن‌ها نیز ضروری است، استفاده می‌گردد.
 
-**LICENSE.txt**: این فایل پروانه‌ انتشار پروژه را شامل می‌شود و اغلب حاوی یک کپی از متن پروانه‌های متن باز رایج به مانند `MIT <http://opensource.org/licenses/MIT>`_ ،`GPL <http://opensource.org/licenses/GPL-3.0>`_ یا `BSD <http://opensource.org/licenses/BSD-3-Clause>`_ می‌باشد.
+ساختار ابتدایی تنها شامل سورس کد می‌بود ولی در این ساختار تمام سورس کد در قالب یک بسته پایتون بخشی از مجموعه بزرگتری است که در آن یک سری فایل به مانند requirements.txt ،README.rst و pyproject.toml افزوده شده است.  تاکید می‌شود که در حال حاضر نیازی به رعایت این ساختار و ایجاد تمامی این فایل‌ها نیست. 
 
-.. note::
-    لازم است تمامی فایل‌های یاد شده و دایرکتوری docs در بالاترین شاخه از دایرکتوری پروژه قرار داده شوند.
+اکنون می توان از روی این پروژه یک توزیع (Distribution) ایجاد و آن را با استفاده از ابزارهایی به مانند  `Twine <https://twine.readthedocs.io/en/stable/>`_ یا `Poetry <https://python-poetry.org/>`_ بر روی PyPI منتشر ساخت. [برای کسب اطلاعات بیشتر می‌توانید از `اسناد پایتون <https://packaging.python.org/en/latest/tutorials/packaging-projects/>`_ استفاده نمایید]
 
-**docs**: در این دایرکتوری اسناد (راهنما، آموزش و...)  پروژه قرار داده می‌شوند. ایجاد این اسناد توسط `Sphinx <http://sphinx-doc.org/>`_ در درسی جداگانه بررسی خواهد شد.
+در صورت علاقه می‌توانید نگاهی نیز به پروژه `saeiddrv/PackagingPythonProjects <https://github.com/saeiddrv/PackagingPythonProjects>`_ بیاندازید که تمامی مراحل را به صورت کاربردی پیاده‌سازی کرده است.
 
-**test**: این دایرکتوری محل نگهداری برنامه تست پروژه می‌باشد. ایجاد تست پروژه نیز در درسی جداگانه بررسی می‌گردد. این دایرکتوری می‌تواند هم  در بالا ترین شاخه از پروژه و هم در داخل دایرکتوری سورس کد قرار داده شود.
 
-با ایجاد یک توزیع (Distribution) از این ساختار و انتشار آن [که در آینده خواهید آموخت]، امکان نصب پروژه از طریق pip به وجود می‌آید. معمولا به جای واژه «توزیع» از واژه «بسته» (Package) استفاده می‌گردد؛ همانطور که pip نیز «سیستم مدیریت بسته پایتون» نامیده می‌شود و هیچگاه نباید آن را با مفهوم «بسته» که تا پیش از این مطرح شده است اشتباه گرفت.
+.. _source-code: 
 
 ایجاد سورس کد
 ---------------