edited l03

Author: Saeid Darvish

source/lessons/l03-create-and-run-a-python-project.rst

@@ -29,9 +29,9 @@
 
 ----
 
-.. _project-structure: 
+.. _definations: 
 
-ساختار پروژه
+تعاریف
 --------------
 
 سورس کد یک پروژه به زبان پایتون در قالب یک یا چند «ماژول» (Module) توسعه می‌یابد که در سورس کدهایی با بیش از یک ماژول بهتر است ماژول‌هایی که از نظر منطقی با یکدیگر مرتبط هستند را درون دایرکتوری‌هایی مجزا قرار دهیم که به این نوع دایرکتوری‌ها در زبان پایتون «بسته» (Package) گفته می‌شود.
@@ -40,68 +40,41 @@
     یک یا چند ماژول درون یک دایرکتوری مشخص تشکیل یک بسته را می‌دهند و هر بسته خود می‌تواند حاوی بسته‌(های) دیگری باشد. 
 
 .. 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) که همان تعریف قدیمی از بسته می‌باشد و بسته فضانام گسترش یافته است.
+
+    در واقع، تا قبل از پایتون 3.3 هر بسته پایتون می‌بایست حاوی یک فایل ``init__.py__`` باشد ولی اکنون نیازی به این فایل نیست و مفسر پایتون اکنون می‌تواند تمامی بسته‌های داخل پرو‌ژه را محل یابی کند. در این درس به منظور شفاف‌سازی بسته‌ها از روش Regular Package استفاده خواهد شد.
 
 در تعریف زبان پایتون دو نوع ماژول وجود دارد:
 
-۱- Pure Module (ماژول عادی)، همان تعریف عادی از ماژول پایتون است؛ فایل‌هایی با پسوند py که کد (تعاریف و دستورات) پایتون در آن‌ها نوشته می‌شوند.
+۱- Pure Module (ماژول عادی)، همان تعریف عادی از ماژول پایتون است؛ فایل‌هایی با پسوند py که کد (تعاریف و دستورات) به زبان پایتون در آن‌ها نوشته می‌شود.
 
-۲- 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 را تهیه نمایید.
+۲- 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 خواهد بود، مگر اینکه نام «ماژول توسعه» به صراحت ذکر گردد.
 
-در ایجاد یک پروژه از پایتون هیچ اجباری به رعایت ساختار خاصی نیست و حتی سورس کد یک پروژه می‌تواند تنها شامل یک ماژول باشد. به عنوان نمونه، شمای پایین از پروژه فرضی SampleProject را در نظر بگیرید:
+در ایجاد یک پروژه از پایتون هیچ اجباری به رعایت ساختار خاصی نیست و سورس کد یک پروژه می‌تواند تنها شامل یک ماژول (فایل با پسوند py.) باشد. به عنوان نمونه، شمای پایین از پروژه فرضی SampleProject را در نظر بگیرید:
 
 .. code::
     
     SampleProject
     .
     ├── sample_project.py
-    ├── module_one.py
     └── pakage/
         ├── __init__.py
         ├── module_two.py
-        └── module_three.py
+        └── module_one.py
 
 .. tip::
-    در پایتون هر **بسته‌ عادی** می‌بایست حاوی فایل ویژه‌‌‌ init\_\_.py_\_\  باشد که البته الزامی به کدنویسی درون این فایل وجود ندارد. این فایل دایرکتوری خود را به عنوان یک بسته (محلی برای یافتن ماژول‌های مرتبط) به مفسر پایتون معرفی می‌کند.
+    در پایتون هر **Regular Package** می‌بایست حاوی فایل ویژه‌‌‌ ``init__.py__``  باشد که البته الزامی به کدنویسی درون این فایل وجود ندارد. این فایل دایرکتوری خود را به عنوان یک بسته (محلی برای یافتن ماژول‌های مرتبط) به مفسر پایتون معرفی می‌کند.
 
-در ایجاد سورس کد باید به صورتی عمل شود که با اجرای یک ماژول‌ مشخص تمام برنامه اجرا گردد. این ماژول معمولا هم نام پروژه در نظر گرفته و با عنوان «اسکریپت» (Script) از آن یاد می‌شود (اینجا:‌ sample_project.py). در واقع اسکریپت، ماژولی است که با هدف اجرای برنامه توسعه می‌یابد و ایجاد سورس کد نیز از آن شروع می‌گردد. از طرفی همانطور که می‌دانیم یکی از ویژگی‌های پایتون امکان برنامه نویسی ماژولار (`Modular <http://en.wikipedia.org/wiki/Modular_programming>`_) است به این صورت که می‌توان کد‌های خود را بر حسب نیاز در ماژول‌هایی جداگانه نوشت و با وارد کردن (Import) آن‌ها در اسکریپت (یا ماژول‌های دیگر) از کد درون آن‌ها استفاده نمود. با این منطق می‌شود سورس کد یک پروژه از پایتون را تنها شامل یک اسکریپت تصور کرد که می‌تواند توسط تعدادی ماژول گسترش یابد؛ البته ممکن است ماژول‌ها نیز بر حسب نیاز در بسته‌هایی جداگانه قرار گرفته باشند.
+در ایجاد سورس کد باید به صورتی عمل شود که با اجرای یک ماژول‌ مشخص تمام برنامه اجرا گردد. این ماژول معمولا هم نام پروژه در نظر گرفته و با عنوان «اسکریپت» (Script) از آن یاد می‌شود (اینجا:‌ sample_project.py). در واقع اسکریپت، ماژولی است که با هدف اجرای برنامه توسعه می‌یابد و ایجاد سورس کد نیز از آن شروع می‌گردد. 
 
 .. tip::
-    [`PEP 8 <http://www.python.org/dev/peps/pep-0008/>`_]: در نام‌گذاری ماژول‌ها تنها از حروف کوچک استفاده می‌شود و در صورت نیاز می‌توان از کاراکتر خط زیرین (``_``) نیز استفاده نمود. نام بسته‌ها کوتاه بوده و از حروف کوچک تشکیل می‌گردد؛ استفاده از ``_`` در نام بسته پیشنهاد نمی‌شود.
-
-اکنون اطلاعات کافی برای شروع یک پروژه از پایتون را دارید ولی چنانچه می‌خواهید با ساختار مناسب پروژه‌ای که قرار است برای استفاده افراد دیگر از طریق PyPI یا سرویس‌هایی نظیر github.com منتشر شود (مانند یک کتابخانه کاربردی) آشنا شوید، ادامه این بخش را نیز مطالعه نمایید. در غیر این صورت می‌توانید به بخش بعدی از همین درس `پرش <#source-code>`_ نمایید.
-
-جدا از سورس کد لازم است موارد دیگری نیز در ساختار این نوع پروژه‌ها در نظر گرفته شود؛ به ساختار پایین توجه نمایید:
-
-
-.. code::
-    
-    my_project
-    .
-    ├── pyproject.toml
-    │
-    ├── LICENSE.txt
-    ├── README.rst
-    ├── requirements.txt
-    │
-    ├── src/
-    │   └── unique_pakage_name/
-    │       ├── __init__.py
-    │       └── main.py
-    │   
-    ├── docs/
-    └── test/
-
-
-ساختار ابتدایی تنها شامل سورس کد می‌بود ولی در این ساختار تمام سورس کد در قالب یک بسته پایتون بخشی از مجموعه بزرگتری است که در آن یک سری فایل به مانند requirements.txt ،README.rst و pyproject.toml افزوده شده است.  تاکید می‌شود که در حال حاضر نیازی به رعایت این ساختار و ایجاد تمامی این فایل‌ها نیست. 
-
-اکنون می توان از روی این پروژه یک توزیع (Distribution) ایجاد و آن را با استفاده از ابزارهایی به مانند  `Twine <https://twine.readthedocs.io/en/stable/>`_ یا `Poetry <https://python-poetry.org/>`_ بر روی PyPI منتشر ساخت. [برای کسب اطلاعات بیشتر می‌توانید از `اسناد پایتون <https://packaging.python.org/en/latest/tutorials/packaging-projects/>`_ استفاده نمایید]
-
-در صورت علاقه می‌توانید نگاهی نیز به پروژه `saeiddrv/PackagingPythonProjects <https://github.com/saeiddrv/PackagingPythonProjects>`_ بیاندازید که تمامی مراحل را به صورت کاربردی پیاده‌سازی کرده است.
+  هر پروژه پایتون باید حاوی یک و تنها یک اسکریپت باشد ولی می‌تواند هیچ، یک یا چند ماژول داشته باشد  که این ماژول‌ها نیز می‌توانند در قالب بسته‌هایی جداگانه سازمان‌دهی شوند. 
 
+.. tip::
+    [`PEP 8 <http://www.python.org/dev/peps/pep-0008/>`_]: در نام‌گذاری ماژول‌ها تنها از حروف کوچک استفاده می‌شود و در صورت نیاز می‌توان از کاراکتر خط زیرین (``_``) نیز استفاده نمود (اما پیشنهاد نمی‌شود). نام بسته‌ها کوتاه بوده و از حروف کوچک تشکیل می‌گردد.
 
 .. _source-code: 
 
@@ -280,6 +253,13 @@
     IDE یا Integrated development environment به ابزارهایی گفته می‌شود که علاوه‌بر یک ویرایشگر متن پیشرفته، امکانات بسیار کاربردی دیگری را نیز به مانند دیباگر (`Debugger <https://en.wikipedia.org/wiki/Debugger>`__) در اختیار برنامه‌نویس قرار می‌دهد.
 
 
+.. _python-import: 
+
+دستور import
+---------------
+
+
+
 پشت صحنه اجرا
 ---------------
 زمانی که اقدام به اجرای یک اسکریپت می‌کنید؛ ابتدا، اسکریپت و تمام ماژول‌های وارد شده در آن به بایت‌کد کامپایل و سپس بایت‌کد‌های حاصل جهت تفسیر به زبان ماشین و اجرا، به ماشین مجازی فرستاده می‌شوند. آنچه ما از آن به عنوان مفسر پایتون (پیاده‌سازی CPython) یاد می‌کنیم در واقع ترکیبی از یک کامپایلر و یک ماشین مجازی است. تصویر پایین به خوبی روند اجرای کدهای پایتون را نمایش می‌دهد.
@@ -420,6 +400,44 @@ pyvenv
     >
 
 
+.. _packaging-projects: 
+
+انتشار پروژه
+--------------
+
+
+اکنون اطلاعات کافی برای شروع یک پروژه از پایتون را دارید ولی چنانچه می‌خواهید با ساختار مناسب پروژه‌ای که قرار است برای استفاده افراد دیگر از طریق PyPI یا سرویس‌هایی نظیر github.com منتشر شود (مانند یک کتابخانه کاربردی) آشنا شوید، ادامه این بخش را نیز مطالعه نمایید. در غیر این صورت می‌توانید به بخش بعدی از همین درس `پرش <#source-code>`_ نمایید.
+
+جدا از سورس کد لازم است موارد دیگری نیز در ساختار این نوع پروژه‌ها در نظر گرفته شود؛ به ساختار پایین توجه نمایید:
+
+
+.. code::
+    
+    my_project
+    .
+    ├── pyproject.toml
+    │
+    ├── LICENSE.txt
+    ├── README.rst
+    ├── requirements.txt
+    │
+    ├── src/
+    │   └── unique_pakage_name/
+    │       ├── __init__.py
+    │       └── main.py
+    │   
+    ├── docs/
+    └── test/
+
+
+ساختار ابتدایی تنها شامل سورس کد می‌بود ولی در این ساختار تمام سورس کد در قالب یک بسته پایتون بخشی از مجموعه بزرگتری است که در آن یک سری فایل به مانند requirements.txt ،README.rst و pyproject.toml افزوده شده است.  تاکید می‌شود که در حال حاضر نیازی به رعایت این ساختار و ایجاد تمامی این فایل‌ها نیست. 
+
+اکنون می توان از روی این پروژه یک توزیع (Distribution) ایجاد و آن را با استفاده از ابزارهایی به مانند  `Twine <https://twine.readthedocs.io/en/stable/>`_ یا `Poetry <https://python-poetry.org/>`_ بر روی PyPI منتشر ساخت. [برای کسب اطلاعات بیشتر می‌توانید از `اسناد پایتون <https://packaging.python.org/en/latest/tutorials/packaging-projects/>`_ استفاده نمایید]
+
+در صورت علاقه می‌توانید نگاهی نیز به پروژه `saeiddrv/PackagingPythonProjects <https://github.com/saeiddrv/PackagingPythonProjects>`_ بیاندازید که تمامی مراحل را به صورت کاربردی پیاده‌سازی کرده است.
+
+
+
 |
 
 ----