وحدات بايثون والاستيراد: import و from و pip

كل ملف هو وحدة

بمجرد أن يتجاوز مشروعك في بايثون حدود السكربت الواحد، ستحتاج إلى تقسيمه على عدة ملفات. ونظام وحدات بايثون بسيط جدًا: أي ملف بامتداد .py يُعتبر تلقائيًا وحدة (module) يمكن استيرادها باسمها.

لنفترض أن لديك ملفًا باسم util.py:

# util.py
def greet(name):
    return f"Hello, {name}"

PI = 3.14159

من ملف آخر في نفس المجلد — main.py — يمكنك استخدامها كالتالي:

# main.py
import util

print(util.greet("Ada"))
print(util.PI)

شغّل الأمر python3 main.py، وسيعثر بايثون على ملف util.py وينفذه مرة واحدة، ثم يُتيح كل ما هو مُعرَّف في المستوى الأعلى (دوال ومتغيرات وأصناف) كخصائص تابعة لوحدة util.

الأشكال الثلاثة لاستيراد الوحدات في بايثون

استيراد الوحدة بالكامل. في هذه الحالة نصل إلى محتوياتها عبر اسم الوحدة نفسها:

استيراد أسماء محددة. بهذه الطريقة تصبح متاحة للاستخدام مباشرةً:

الاستيراد مع اسم مستعار (alias). مفيد لما يكون اسم الوحدة طويل، أو لما تتعارض وحدتان بنفس الاسم:

import numpy as np
import pandas as pd

# Now use np.array(...), pd.DataFrame(...), etc.

هناك صيغة رابعة، وهي from math import *، تقوم بسحب كل شيء إلى مساحة الأسماء عندك. تجنّبها خارج تجارب REPL السريعة، لأنها تجعل من المستحيل معرفة مصدر أي اسم، كما أنها تتسبب في تضارب صامت بين الأسماء.

متى تُنفَّذ عمليات الاستيراد في بايثون

يقوم بايثون بتنفيذ الكود الموجود في المستوى الأعلى من الوحدة المستوردة مرة واحدة فقط، عند أول استيراد لها في البرنامج. أما عمليات الاستيراد اللاحقة لنفس الوحدة فتُرجع النسخة المحمّلة سابقًا. وبالتالي، هذا:

# setup.py
print("setup module loading...")
VALUE = 42

# main.py
import setup
import setup  # imported twice — but "loading" only prints once
print(setup.VALUE)

تُطبع "setup module loading..." مرة واحدة فقط. هذه نقطة مهمة: إذا وضعت تأثيرات جانبية (مثل فتح ملف أو الطباعة) في المستوى الأعلى من الوحدة، فإنها تُنفَّذ وقت الاستيراد، وهذا في الغالب ليس ما تريده. ضع هذه الأمور داخل دوال.

المكتبة القياسية في بايثون

تأتي بايثون مزوّدة بمكتبة قياسية ضخمة من الوحدات، وقد رأيت بعضها سابقًا. وهذه بعض الوحدات التي ستحتاجها باستمرار:

• math — الجذر التربيعي، الجيب، اللوغاريتم، وثوابت مثل pi و e.
• random — توليد أرقام عشوائية، اختيارات، وخلط العناصر.
• datetime — التعامل مع التواريخ والأوقات.
• json — قراءة وكتابة بيانات JSON.
• os, os.path — مسارات نظام الملفات والعمليات عليها.
• pathlib — طريقة حديثة للتعامل مع المسارات، وغالبًا تكون أفضل من os.path.
• re — التعابير النمطية (Regular Expressions).
• collections — أنواع تجميعات متخصصة مثل (Counter, defaultdict, deque، وغيرها).
• itertools, functools — أدوات مساعدة للمكرّرات والدوال.
• csv — قراءة وكتابة ملفات CSV.

المكتبة القياسية مثبّتة مسبقًا — لا حاجة لأي pip install.

الحزم الخارجية وأداة pip

كل ما لا تغطيه المكتبة القياسية في بايثون ستجده على الأرجح في فهرس حزم بايثون (PyPI)، الذي يضم مئات الآلاف من الحزم الجاهزة للاستخدام. تثبيت أي حزمة منها يتم عبر الأمر pip:

pip install requests
pip install pandas
pip install --upgrade requests
pip uninstall requests

بمجرد تثبيتها، تقدر تستوردها مثل أي وحدة عادية:

import requests

response = requests.get("https://api.example.com/data")
print(response.status_code)

إليك بعض النصائح للتعامل مع هذا الأمر بذكاء:

استخدم البيئات الافتراضية

تثبيت كل شيء على مستوى النظام يجلب لك المتاعب فقط. كل مشروع يحتاج إصدارات مختلفة، وبعض الحزم مرتبطة بإصدار معيّن من بايثون، فضلاً عن أن التثبيت العام يتطلب صلاحيات المدير في بعض الأنظمة. الحل هو البيئة الافتراضية (virtual environment)، وهي نسخة بايثون معزولة مخصصة لمشروع واحد فقط:

python3 -m venv .venv
source .venv/bin/activate    # macOS/Linux
.venv\Scripts\activate       # Windows

pip install requests

طالما أن البيئة الافتراضية مُفعَّلة، فإن pip يُثبِّت الحزم داخل مجلد المشروع فقط، وليس على النظام كله. لإلغاء التفعيل عند الانتهاء، استخدم الأمر deactivate.

تثبيت نسخ الاعتماديات

احفظ قائمة الحزم المُثبَّتة حتى يتمكن الآخرون (وأنت نفسك مستقبلًا) من إعادة بناء نفس البيئة:

pip freeze > requirements.txt

Then later:

pip install -r requirements.txt

أدوات مثل Poetry و pipenv و uv تتعامل مع هذا الموضوع بشكل أكثر سلاسة، لكن الطريقة التقليدية pip + requirements.txt تبقى خيارًا جيدًا في مرحلة التعلّم.

كتابة وحدات بايثون الخاصة بك

عندما تتراكم لديك دوال تحتاج إلى إعادة استخدامها في ملفات متعددة، ضعها في وحدة (module) مستقلة. إليك الأعراف المتبعة في التسمية:

• أسماء الملفات تُكتب بصيغة lower_snake_case.py.
• الدوال والمتغيرات على مستوى الوحدة تُكتب هي الأخرى بصيغة lower_snake_case.
• أما الأصناف (classes) فتُكتب بصيغة PascalCase.

# shopping.py
PRICES = {"apple": 0.50, "bread": 2.00}

def total(items):
    return sum(PRICES[item] for item in items)

# main.py
from shopping import total, PRICES

print(total(["apple", "bread"]))
print(PRICES)

إذا كان هناك ملفان في نفس المجلد يستورد كلّ منهما الآخر، فقد تقع دون قصد في فخ الاستيراد الدائري (circular import). الحلّ المعتاد هو نقل الكود المشترك إلى ملف ثالث يستورده الاثنان معًا.

الحزم: مجلدات تضمّ وحدات بايثون

عندما يصبح لديك عدد لا بأس به من الوحدات، جمّعها داخل حزمة (package)، أي مجلد يحتوي على ملف __init__.py:

myproject/
├── main.py
└── utils/
    ├── __init__.py
    ├── text.py
    └── numbers.py

ثم:

from utils.text import slugify
from utils import numbers

print(slugify("Hello, World"))
print(numbers.mean([1, 2, 3]))

يمكن أن يكون ملف __init__.py فارغًا تمامًا؛ فمجرد وجوده هو ما يجعل من utils حزمة (package). تدعم إصدارات بايثون الحديثة أيضًا ما يُعرف بـ "namespace packages" دون الحاجة إلى __init__.py، لكن في البداية يبقى الأسلوب الصريح أوضح وأسهل للفهم.

قائمة سريعة عند تعطّل الاستيراد في بايثون

• "ModuleNotFoundError: No module named X". إمّا أن الحزمة غير مثبّتة أصلًا، أو أنك تُشغّل بايثون من مُفسِّر مختلف عن ذلك الذي استخدمته مع pip install. إن كنت تعمل داخل بيئة افتراضية (venv)، تأكّد من تفعيلها أولًا.
• "ImportError: cannot import name Y from X". الوحدة (module) موجودة، لكن الاسم الذي طلبته غير موجود داخلها. راجِع الأخطاء الإملائية وألقِ نظرة على المحتوى الفعلي للوحدة.
• "Circular import". وحدتان تستوردان بعضهما البعض بشكل دائري. الحل هو نقل الكود المشترك إلى وحدة ثالثة مستقلة.

الخطوة التالية: تثبيت مكتبات خارجية

وحداتك الخاصة ستأخذك بعيدًا، لكن أغلب المشاريع الحقيقية تعتمد أيضًا على مكتبات من مستودع PyPI — مثل requests وpandas وأطر الاختبار. الصفحة القادمة تشرح أداة pip، وكيفية تثبيت مكتبة بايثون بشكل نظيف، وكيف تُوثّق الاعتماديات (dependencies) التي يحتاجها مشروعك.