الحزم وهيكل المشروع

من ملف إلى مجلد من الوحدات

لا يكفي ملف واحد حين يكبر المشروع. الحزمة (package) مجلد من الوحدات تستطيع بايثون استيراده كوحدة واحدة. علّم المجلد بملف اسمه __init__.py (يمكن أن يكون فارغًا) فيصبح كل ملف .py بداخله وحدة في الحزمة، تُسمّى بالنقاط: quant/pricing.py هو quant.pricing، وquant/data/loaders.py هو quant.data.loaders. والمجلدات داخل الحزمة حزم فرعية وتحتاج كل منها إلى __init__.py خاص بها.

# A small project on disk
#
# quant-tools/
#   pyproject.toml
#   README.md
#   quant/
#     __init__.py
#     pricing.py
#     data/
#       __init__.py
#       loaders.py
#   tests/
#     test_pricing.py

# quant/pricing.py
def mid(bid, ask):
    return (bid + ask) / 2

# anywhere else in the project
from quant.pricing import mid
import quant.data.loaders

print(mid(184.0, 185.0))  # 184.5

تخطيط يتسع للنمو

أبقِ الكود القابل للاستيراد في مجلد حزمة واحد باسم المشروع، وأبقِ كل شيء آخر بجانبه لا بداخله: الاختبارات في tests/، وملف README.md يشرح المشروع، وملف pyproject.toml يسمّيه ويسرد اعتماداته، والبيانات أو الدفاتر في مجلداتها. وتُسمّى ملفات الاختبار test_*.py لتجدها أدوات مثل pytest. والوحدات الصغيرة المركّزة ذات الأسماء الواضحة (pricing.py وloaders.py) أسهل اختبارًا وإعادة استخدامًا من utils.py طويل واحد.

# pyproject.toml (names the project and its dependencies)
#
# [project]
# name = "quant-tools"
# version = "0.1.0"
# requires-python = ">=3.11"
# dependencies = ["numpy"]

# tests/test_pricing.py: found automatically because of the name
from quant.pricing import mid

def test_mid():
    assert mid(184.0, 185.0) == 184.5

الاستيراد داخل الحزمة

داخل الحزمة يمكنك الاستيراد بالمسار الكامل من الأعلى (from quant.pricing import mid، استيراد مطلق) أو نسبةً إلى الوحدة الحالية (from .pricing import mid، نقطة للحزمة نفسها ونقطتان لأصلها، استيراد نسبي). والاستيراد المطلق أوضح عادةً. يُنفَّذ __init__.py عند أول استيراد للحزمة، فيمكنه إعادة تصدير الأسماء التي يحتاجها المستخدمون (from .pricing import mid) فيعمل import quant; quant.mid(...). شغّل كود الحزمة بـpython -m quant.data.loaders لا بـpython quant/data/loaders.py لتُحَلّ الأسماء ذات النقاط.

# quant/__init__.py: runs on the first "import quant"
from .pricing import mid          # relative: same package

__all__ = ["mid"]                 # what "from quant import *" would give

# quant/data/loaders.py
from quant.pricing import mid     # absolute: always starts at the top
from .. import pricing            # relative: two dots = the parent package

# In a terminal, from the project folder:
#   python -m quant.data.loaders   (runs the module as part of the package)
#   pytest -q                      (finds tests/test_*.py)

# A file path and its module name are two spellings of one thing
path = "quant/data/loaders.py"
name = path[:-3].replace("/", ".")
print(name)                          # quant.data.loaders
print(name.split(".")[0])            # quant  (the top-level package)

# __init__.py stands for its folder
print("quant/__init__.py"[:-3].replace("/", "."))  # quant.__init__ -> the package is "quant"

• الحزمة مجلد فيه __init__.py؛ وquant/data/loaders.py هو الوحدة quant.data.loaders.
• ضع الكود في الحزمة؛ والاختبارات وREADME وpyproject.toml والبيانات بجانبها.
• فضّل الاستيراد المطلق؛ وشغّل كود الحزمة بـpython -m package.module.

التالي: البيئات الافتراضية وpip، ليحصل كل مشروع على المكتبات التي يحتاجها بالضبط.

المختبر: ما الذي يُقيَّم

• حوّل مسار ملف إلى اسم وحدة باستخدام module_name25 نقطة
• اسرد الوحدات القابلة للاستيراد في مشروع باستخدام find_modules25 نقطة
• اكتشف المجلدات التي تفتقر إلى __init__.py باستخدام missing_init25 نقطة
• اكتب جملة استيراد وحدة باستخدام import_line25 نقطة