كيفية إصلاح خطأ الاستيراد الذي حدث أثناء محاولة الاستيراد النسبي مع عدم وجود حزمة أصلية معروفة

الخطأخطأ الاستيراد: محاولة استيراد نسبي بدون حزمة أصلية معروفة في بايثون يربك العديد من المطورين. يحدث ذلك عند تشغيل ملف يستخدم الواردات النسبية كبرنامج نصي بدلاً من استخدامه كجزء من الحزمة. وإليك سبب حدوث ذلك وكيفية إصلاحه.

لماذا يحدث هذا

تعمل عمليات الاستيراد النسبية (from .module import x) فقط عندما تعرف بايثون أن الملف جزء من الحزمة. عندما تقوم بتشغيل ملف مباشرة (python myfile.py)، فإن بايثون تتعامل معه كبرنامج نصي عالي المستوى بدون حزمة أصل – لذلك تفشل عمليات الاستيراد النسبية.. في الاستيراد لا توجد حزمة مرتبطة بها.

الإعداد الذي يقوم بتشغيله

# Project structure
myproject/
├── mypackage/
│   ├── __init__.py
│   ├── main.py
│   └── helper.py

# main.py uses a relative import
# from .helper import do_something

# 🐛 Running directly fails
python mypackage/main.py
# ImportError: attempted relative import with no known parent package

الإصلاح 1: تشغيل كوحدة مع -m

# Run from the PROJECT ROOT (parent of mypackage) using -m
cd myproject
python -m mypackage.main

# The -m flag runs it as a module within the package,
# so Python knows the parent package and relative imports work

هذه هي الطريقة الصحيحة لتشغيل تعليمات الحزمة البرمجية التي تستخدم الواردات النسبية. لاحظ أنك تعمل من جذر المشروع وتستخدم النقاط، وليس الخطوط المائلة.

الإصلاح 2: استخدام الواردات المطلقة

# Instead of relative imports:
# from .helper import do_something          # relative

# Use absolute imports:
from mypackage.helper import do_something   # absolute

# Absolute imports work whether run as a script or module,
# as long as the package is on the Python path

الإصلاح 3: إضافة نقطة إدخال مناسبة

# Create a run script at the project root (outside the package)
# myproject/run.py
from mypackage.main import main

if __name__ == '__main__':
    main()

# Run it from the root — absolute imports resolve correctly
python run.py

الإصلاح 4: اجعلها حزمة مناسبة قابلة للتثبيت

# pyproject.toml
[project]
name = "mypackage"
version = "0.1.0"

[project.scripts]
mypackage = "mypackage.main:main"

# Install in editable mode
pip install -e .

# Now run via the entry point — imports work correctly
mypackage
# Or: python -m mypackage.main

فهم الواردات النسبية مقابل المطلقة

# Relative imports (need a parent package)
from . import sibling_module        # same package
from .helper import func            # module in same package
from ..other_package import thing   # parent package

# Absolute imports (need package on path)
from mypackage.helper import func
from mypackage.subpackage.mod import thing

# Rule of thumb: absolute imports are more explicit and robust.
# Use them unless you have a specific reason for relative imports.

متطلبات __init__.py

# For a directory to be a package (enabling relative imports),
# it typically needs an __init__.py file:

mypackage/
├── __init__.py       # makes mypackage a package (can be empty)
├── main.py
└── helper.py

# Without __init__.py, Python may treat it as a namespace package
# (works in modern Python but can cause confusion). For clarity,
# include __init__.py in packages that use relative imports.

دليل القرار السريع

• تشغيل ملف حزمة للتطوير؟ استخدمpython -m package.module من جذر المشروع
• هل تريد الواردات التي تعمل دائمًا؟ استخدم الواردات المطلقة (from mypackage.x import y)
• بناء مشروع حقيقي؟اجعلها حزمة قابلة للتثبيت مع نقطة إدخال
• مجرد برنامج نصي بسيط؟لا تستخدم الواردات النسبية – استخدم المطلق أو ضع كل شيء في ملف واحد

الأسئلة المتداولة

س: لماذا تعمل عمليات الاستيراد النسبية في بعض الملفات دون غيرها؟
ج: تعمل عندما يتم استيراد الملف كجزء من حزمة، ولكنها تفشل عند تشغيلها مباشرة كبرنامج نصي. same file can work when imported and fail when run with python file.py — because direct execution has no parent package.

Q: Should I use relative or absolute imports?
A: Absolute imports are generally recommended — they’re explicit, work in more situations, and are clearer about where things come from. Use relative imports only within a package when it improves readability, and understand they require running as a module.

Q: What does the -m flag actually do?
A: It runs a module as part of its package, setting up the package context so relative imports resolve. python -m mypackage.main tells Python “run main as a module inside mypackage,” giving it the parent package it needs.

Q: Do I always need __init__.py?
A: In modern Python, namespace packages work without it, but including __init__.py makes your package explicit and avoids ambiguity, especially when using relative imports. It’s good practice to include it.

Q: My IDE runs it fine but the terminal fails. Why?
A: IDEs often set the working directory and Python path to the project root and may run files as modules. Replicate that in the terminal: run from the project root with python -m package.module, or configure your path/entry point to match.

Conclusion

“Attempted relative import with no known parent package” means you’re running a package file directly as a script, so relative لا تحتوي عمليات الاستيراد على حزمة أصل يمكن حلها. الإصلاحات: قم بتشغيلها كوحدة مع من جذر المشروع، أو قم بالتبديل إلى عمليات الاستيراد المطلقة ( )، أو قم بإنشاء نقطة إدخال مناسبة في جذر المشروع ، اجعلها حزمة قابلة للتثبيت مع نقطة إدخال.“Attempted relative import with no known parent package” means you’re running a package file directly as a script, so relative لا تحتوي عمليات الاستيراد على حزمة أصل يمكن حلها. الإصلاحات: قم بتشغيلها كوحدة مع من جذر المشروع، أو قم بالتبديل إلى عمليات الاستيراد المطلقة ( )، أو قم بإنشاء نقطة إدخال مناسبة في جذر المشروع ، اجعلها حزمة قابلة للتثبيت مع نقطة إدخال.python -m mypackage.main“Attempted relative import with no known parent package” means you’re running a package file directly as a script, so relative لا تحتوي عمليات الاستيراد على حزمة أصل يمكن حلها. الإصلاحات: قم بتشغيلها كوحدة مع من جذر المشروع، أو قم بالتبديل إلى عمليات الاستيراد المطلقة ( )، أو قم بإنشاء نقطة إدخال مناسبة في جذر المشروع ، اجعلها حزمة قابلة للتثبيت مع نقطة إدخال.from mypackage.helper import x“Attempted relative import with no known parent package” means you’re running a package file directly as a script, so relative لا تحتوي عمليات الاستيراد على حزمة أصل يمكن حلها. الإصلاحات: قم بتشغيلها كوحدة مع من جذر المشروع، أو قم بالتبديل إلى عمليات الاستيراد المطلقة ( )، أو قم بإنشاء نقطة إدخال مناسبة في جذر المشروع ، اجعلها حزمة قابلة للتثبيت مع نقطة إدخال.“Attempted relative import with no known parent package” means you’re running a package file directly as a script, so relative لا تحتوي عمليات الاستيراد على حزمة أصل يمكن حلها. الإصلاحات: قم بتشغيلها كوحدة مع من جذر المشروع، أو قم بالتبديل إلى عمليات الاستيراد المطلقة ( )، أو قم بإنشاء نقطة إدخال مناسبة في جذر المشروع ، اجعلها حزمة قابلة للتثبيت مع نقطة إدخال.