ثبّت حزمة Qiskit v1.0 الجديدة

يستخدم Qiskit v1.0 هيكلًا مختلفًا للتعبئة مقارنةً بالإصدارات السابقة، وهو ما قد يُسبّب مشاكل في البيئات التي تعتمد على حزم غير متوافقة بعد مع Qiskit v1.0.

تنبيه

لا تحاول ترقية بيئة Python الافتراضية الحالية إلى Qiskit v1.0 في مكانها مباشرةً.

لن نُجري تغييرات مشابهة في التعبئة في المستقبل. هذا حدث استثنائي مرتبط بإصدار Qiskit v1.0 تحديدًا، وذلك لنجعل عملية التعبئة أيسر ما يمكن في المستقبل.

هذا الدليل مقسّم إلى الأقسام التالية. لا تحتاج إلى مراجعة سوى الأقسام ذات الصلة بك.

ينبغي للمستخدمين قراءة قسم للمستخدمين.
إذا كنت تُطوّر حزمةً تعتمد على Qiskit أو تُشرف عليها، فاقرأ قسم للمطوّرين.
إذا واجهت مشاكل في تثبيت Qiskit v1.0 أو استيراده، راجع قسم استكشاف الأخطاء وإصلاحها.

إذا كنت مهتمًا بفهم هيكل الحزمة القديم وسبب تغييره، راجع نظرة عامة على تغييرات التعبئة الجذرية.

للمستخدمين

يجب عليك إنشاء بيئة افتراضية جديدة لتثبيت Qiskit v1.0. ترقية التثبيت الحالي في مكانه إلى Qiskit v1.0 أمرٌ بالغ الصعوبة وعرضة للأخطاء.

ملاحظة

تستخدم الأمثلة في هذا القسم وحدة venv المضمّنة في مكتبة Python القياسية. إذا كنت تستخدم أداةً مختلفة مثل virtualenv أو conda، فراجع توثيقها للحصول على المساعدة.

تستخدم أوامر Linux وmacOS صياغةً مشابهة لـ bash. أما أوامر Windows فتستخدم PowerShell.

إنشاء البيئة الجديدة

أنشئ بيئةً افتراضية جديدة في كل مجلد مشروع تعمل عليه، باستخدام الإصدار الذي تفضّله من Python 3.8 أو أحدث.
- macOS
- Linux
- Windows
python3 -m venv .venv
python3 -m venv .venv
python -m venv .venv

فعِّل البيئة.

macOS
Linux
Windows

source .venv/bin/activate

source .venv/bin/activate

.venv\Scripts\activate.ps1

ثبّت الحزم التي تحتاجها. يُنصح بتنفيذ ذلك باستخدام أمر pip install واحد يتضمّن جميع التبعيات.
```
pip install 'qiskit>=1'
```
يمكنك اختياريًا تضمين حزم إضافية بإدراجها كوسائط. مثلًا:
```
pip install 'qiskit>=1' jupyterlab pandas matplotlib
```
يتضمّن Qiskit v1.0 تغييرات جذرية، لذا تمّ وضع علامة على عدة حزم بوصفها غير متوافقة معه بعد. لهذا قد ترى أخطاءً من pip حتى يتم إصدار إصدارات جديدة من تلك الحزم. قد تعتمد الإصدارات القديمة من بعض الحزم أيضًا على حزمة qiskit-terra القديمة. مثل هذه الحزم قد لا تُعطي أخطاءً عند تشغيل هذا الأمر، لكنها قد تُثير خطأً عند تنفيذ import qiskit. يجب ألّا تثبّت أي حزم تعتمد مباشرةً على qiskit-terra.
نصيحة
إحدى طرق إجبار pip على منع qiskit-terra من أوامر install الفردية هي استخدام ملف قيود يُعيّن qiskit-terra على إصدار مستحيل. مثلًا، ملف قيود يتضمّن السطر qiskit-terra>=1.0 سيعني أنه إذا حاولت تبعية تثبيت qiskit-terra، لن يتطابق أي إصدار منشور مع المتطلبات.
لقد وفّرنا مثل هذا الملف في GitHub Gist على https://qisk.it/1-0-constraints، ويمكنك استخدامه هكذا:
pip install -c https://qisk.it/1-0-constraints qiskit [other packages]
إذا كانت إحدى الحزم تتطلّب qiskit-terra، ستظهر لك رسالة فشل في حل التبعيات.
تنبيه
لا تثبّت حزمًا غير متوافقة مع Qiskit v1.0 في هذه البيئة الافتراضية. إذا كنت بحاجة إلى استخدام مثل هذه الحزم، فثبّتها في بيئة افتراضية منفصلة مع Qiskit 0.45 أو 0.46.

إذا كانت لديك بيئة موجودة، يمكنك استخدام pipdeptree للاستعلام عن متطلبات الحزم المثبّتة ومعرفة ما إذا كانت تتطلّب qiskit<1. لأي حزمة تتطلّب qiskit<1، ابحث عن تحديثات تجعلها متوافقة مع Qiskit v1.0.

إذا واجهت مشاكل، راجع قسم استكشاف الأخطاء وإصلاحها، أو اسأل في Qiskit Slack. إذا اعتقدت أن هناك خللًا برمجيًا، يمكنك إنشاء تذكرة في Qiskit.
إذا لم تكن تخطط لاستخدام البيئة فورًا، استخدم أمر deactivate لإلغاء تفعيلها.

استخدام البيئة الجديدة

في كل مرة تبدأ فيها جلسة سطر أوامر جديدة، يجب عليك الانتقال إلى مجلد مشروعك و"تفعيل" البيئة بتشغيل أمر activate:

macOS
Linux
Windows

source .venv/bin/activate

source .venv/bin/activate

.venv\Scripts\activate.ps1

للمطوّرين

إذا كنت تُشرف على حزمة تعتمد على Qiskit، استخدم هذه المعلومات لتتعلّم كيفية التعبير الصحيح عن توافقها واختبارها مع Qiskit v1.0.

التوصيات المتعلقة بالمتطلبات

نوصي بأن تشترط حزمتك qiskit>=0.45,<1 (أو حدًّا أدنى مناسبًا آخر) إذا لم تكن متأكدًا من توافق الحزمة مع Qiskit v1.0. هذه نفس التوصية المُعطاة لضمان التوافق مع NumPy 2.0.

سيُصدر مرشّح إصدار Qiskit v1.0، بالإصدار v1.0.0rc1، في 1 فبراير 2024. ينبغي عليك اختبار حزمتك مقابله، وفي أسرع وقت ممكن، إصدار نسخة جديدة (متوافقة) من حزمتك مع إلغاء تثبيت الحد الأعلى لمتطلباتها.

التوصيات المتعلقة بالاختبار مع Qiskit v1.0

تنطبق هذه التوصيات على الاختبار الاستباقي مقابل فرع Qiskit الرئيسي main، وعلى الاختبار مقابل مرشّح الإصدار v1.0.0rc1 (وما يليه إن وُجد).

لا نوصي في البداية بحماية الفروع اعتمادًا على نجاح CI مقابل فرع Qiskit الرئيسي main، لأن تغييرات Qiskit قد تمنعك من دمج PRs. بعد إصدار مرشّحات Qiskit، وبعد أن تدعم جميع تبعيات حزمتك Qiskit v1.0، نوصي بحماية الفروع اعتمادًا على النجاح مقابل أحدث مرشّح إصدار، لضمان بقاء الحزمة متوافقة مع Qiskit v1.0.

إذا لم تكن حزمتك، ولا أي من تبعياتها المتعدية، تفرض قيدًا على qiskit<1، ينبغي عليك إنشاء بيئة افتراضية للاختبار كما تفعل عادةً، في أمر pip install واحد، وتحديد qiskit==1.0.0rc1 أو qiskit==git+https://github.com/Qiskit/qiskit.git@main مباشرةً حسب الحاجة. هذه هي الطريقة الأكثر موثوقية لضمان حصولك على بيئة صالحة تمامًا.

إذا كان المكوّن الوحيد في رسم بيان تبعيات حزمتك الذي يفرض قيدًا على qiskit<1 هو حزمتك نفسها، فقد تحتاج إلى جعل مجموعة CI الخاصة بك تُعدّل مؤقتًا ملف المتطلبات للسماح بـ Qiskit v1.0 أولًا، ثم تثبيت البيئة دفعةً واحدة كما كان من قبل. بدلًا من ذلك، استخدم القواعد التالية لترقيات البيئات ذات الأغراض العامة، وانتقل إلى حل البيئة الموحّدة بأسرع ما يمكن.

إذا كانت إحدى تبعياتك المتعدية على الأقل لا تمتلك بعد نسخة مُصدَرة تدعم Qiskit v1.0، يجب عليك إجراء تغييرات يدوية. ثمة عدة استراتيجيات يمكن تجربتها، مرتّبة تقريبًا من الأفضل إلى الأقل تفضيلًا:

ثبّت التبعية الإشكالية من فرعها الرئيسي main إذا كانت النسخة التطويرية قد خفّفت القيد، حتى تتمكّن من بناء بيئة الاختبار في خطوة واحدة.
استبعد استخدام تلك التبعية من بيئة الاختبار إن أمكن.
أنشئ بيئة اختبار بالطريقة المعتادة، ثم تجاوزها يدويًا لاستخدام Qiskit v1.0.

الترقية اليدوية لبيئة موجودة

تنبيه

تُنشئ هذه العملية عمدًا بيئةً غير صالحة. لذلك، أي اختبار يُجرى فيها يكون أقل صحةً. قد تبدو الاختبارات ناجحة، لكن هذا لا يضمن توافق الحزمة مع Qiskit v1.0. قد يحدث ذلك لأن البيئة غير متسقة مع نفسها وقد تحتوي على ملفات غير موجودة في بيئة صالحة، أو قد يتغيّر سلوك حزمة مُستبدَلة مع Qiskit v1.0.

ملاحظة

إذا كانت إحدى تبعياتك تُثبّت qiskit<1 حتى على فرع التطوير الخاص بها، فقد لا تعمل بأي شكل مع Qiskit v1.0، وإذا لم تتمكّن اختباراتك من العمل بسبب ذلك، فقد تضطر إلى الانتظار حتى يصبحوا متوافقين (أو العمل معهم على التوافق).

لترقية بيئة في مكانها، اتّبع الخطوات التالية:

أنشئ بيئةً كالمعتاد، مع التأكد من عدم وجود حزم تمدّد فضاء أسماء qiskit أو qiskit.providers.
أزل تثبيت كلٍّ من qiskit وqiskit-terra للتأكد من عدم وجود أي منهما:

pip uninstall --yes qiskit qiskit-terra

في هذه المرحلة، يجب ألّا يحتوي site-packages في البيئة على مجلد qiskit. لا تحتاج إلى التحقق من ذلك في كل تشغيل لـ CI، لكن إذا كنت تُصحّح أخطاء سكريبت محليًا، اتّبع هذه الخطوات للتحقق:

شغّل الأمر التالي من داخل python الخاص بالبيئة الافتراضية:

import site
print(site.getsitepackages())

تحقّق من أن تلك المجلدات لا تحتوي على مجلد qiskit. إذا احتوت عليه، فمن المرجّح أن لديك حزمًا تمدّد فضاء الأسماء مثبّتة، وينبغي عليك إيجادها وإزالة التبعية عليها.
ثبّت الإصدار المستهدف من Qiskit v1.0 بأحد هذه الأوامر:

بعد نشر مرشّح الإصدار المرغوب:
```
pip install 'qiskit==1.0.0rc1'
```
لتبعية من فرع main (أو استبدل أي محدّد مراجعة git تفضّله بعد @):
```
pip install 'git+https://github.com/Qiskit/qiskit.git@main'
```

لديك الآن بيئة تسمح لك Qiskit بالاختبار فيها. إذا أسفر import qiskit عن ImportError، أو إذا كنت تواجه صعوبة في إيجاد تبعياتك، راجع النصائح في قسم الحماية من البيئات غير الصالحة في Qiskit.

نماذج لسير عمل GitHub Actions اليدوية

تُعدّ سير العمل التالية وظيفةً مجدولة للتشغيل ليلًا. تُعدّ هذه الوظيفة بيئةً للاختبار مع Qiskit v1.0 وتُشغّل pytest (أو أي خطوات اختبار تحتاجها).

لحزمة لا تمتلك تبعيات متعدية على qiskit<1:

on:
  schedule:
    - cron: '0 3 * * *'
jobs:
  test_main:
    name: Test Qiskit main
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.10'
      - name: Create environment
        run: |
          set -e
          # First ensure the standard tools are up-to-date.
          python -m pip install --upgrade pip wheel setuptools
          # Note that this resolves everything in a single command.
          # If it fails, at least one package likely requires `qiskit<1`.
          python -m pip install --upgrade \
            -c constraints.txt \
            -r requirements-dev.txt \
            . \
            'git+https://github.com/Qiskit/qiskit.git@main'
      - name: Run tests
        run: pytest

لحزمة لها تبعيات متعدية لا مفرّ منها تُثبّت qiskit<1، أنشئ بيئةً غير صالحة:

on:
  schedule:
    - cron: '0 3 * * *'
jobs:
  test_main:
    name: Test Qiskit main
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.10'
      - name: Create environment
        run: |
          set -e
          python -m pip install --upgrade pip wheel setuptools
          # Install the regular test environment.
          python -m pip install --upgrade \
            -c constraints.txt \
            -r requirements-dev.txt \
            .
          # Uninstall `qiskit` and `qiskit-terra`.
          python -m pip uninstall --yes qiskit qiskit-terra
          # Install the new version of Qiskit
          python -m pip install 'git+https://github.com/Qiskit/qiskit.git@main'
      - name: Run tests
        run: pytest

نموذج لإعداد `tox`

فيما يلي أمثلة على أقسام tox.ini لبناء بيئة اختبار مع Qiskit v1.0 وتشغيل pytest (أو أي خطوات اختبار تحتاجها).

إذا لم يكن ثمة ما يمنع تثبيت Qiskit v1.0 في بيئة صالحة:

[tox]
minversion = 4.0.0

# This environment section should set up your regular test build.
# We'll extend it after, and this one is just an example.
[testenv]
install_command = pip install -c {toxinidir}/constraints.txt -U {opts} {packages}
deps =
    -r{toxinidir}/requirements-dev.txt
commands =
    pytest

# This is an override environment to install Qiskit main.
# We're assuming that you have a requirement like `qiskit>=0.45`
# in your packages metadata requirements.
[testenv:qiskit-main]
# Inherit the base dependencies, and add the additional requirement.
deps =
  [{testenv}deps]
  git+https://github.com/Qiskit/qiskit@main
# All other options, like the `commands` section, are inherited from `testenv`.

إذا كانت حزمتك أو إحدى تبعياتها المتعدية تفرض قيدًا لا مفرّ منه على qiskit<1، نوصي بإجراء هذا الاختبار باستخدام بناء البيئة اليدوي كما هو موضّح في القسم أعلاه، لأن tox يُضيف عدة تعقيدات بسبب صرامته في عزل البيئة وترتيب التثبيت. هذا سلوك صحيح من tox (لا ينبغي لنا بناء بيئة غير صالحة)، لكن بما أننا نعلم مسبقًا أننا نبني بيئةً غير صالحة، فإن هذه الفحوصات تُعيق العملية.

[tox]
minversion = 4.0.0

# This environment section should set up your regular test build.
# We'll extend it later.  This is just an example.
[testenv]
install_command = pip install -c {toxinidir}/constraints.txt -U {opts} {packages}
deps =
    -r{toxinidir}/requirements-dev.txt
commands =
    pytest

[testenv:qiskit-main]
# Set a sequence of commands to run in the environment after everything has been installed,
# but before the main test suite.
commands_pre =
  pip uninstall --yes qiskit qiskit-terra
  pip install 'git+https://github.com/Qiskit/qiskit@main'
# All other sections, like the dependencies and the 'commands' section are inherited.

استكشاف الأخطاء وإصلاحها

التغييرات في تغليف Qiskit v1.0 معقدة، وأداة Python القياسية pip ليست غنية بما يكفي في بعض الجوانب لكي نتمكن من إيصال التغييرات في هياكل التوزيع إليها، مما قد يتسبب للأسف في مشكلات للمستخدمين. لقد حرصنا على أن يفشل Qiskit بشكل سريع وواضح إذا اكتشف بيئة غير صالحة، وذلك دون إطلاق إنذارات كاذبة. نفهم أن المستخدمين قد يجدون رسالة الخطأ مزعجة، لكن تجربتنا تقول إن الانتباه للمشكلة فور حدوثها أفضل بكثير من أن تبدو الأمور وكأنها تعمل بشكل طبيعي، ثم تنهار في وقت لاحق بطرق خفية.

يحتوي هذا القسم على أخطاء التغليف التي قد تصادفها، مع شرح لكيفية حلها.

معظم هذه المشكلات ليست حكرًا على Qiskit، لذا فالنصائح الواردة هنا مفيدة على الأرجح حتى لو كانت الأجزاء الإشكالية غير مرتبطة بـ Qiskit.

`import qiskit` يعطي الخطأ "ModuleNotFoundError: No module named 'qiskit'"

لا يستطيع Python إيجاد تثبيت Qiskit.

إذا كنت قد ثبّتت Qiskit بالفعل، فالأرجح أنك لم تُفعّل البيئة الافتراضية الصحيحة. راجع قسم تفعيل البيئة الافتراضية للاطلاع على التعليمات.

إذا كنت تستخدم Jupyter وظهر لك هذا الخطأ، تأكد من أن Jupyter مثبّت في نفس البيئة الافتراضية التي يوجد فيها Qiskit. اخرج من Jupyter، وفعّل البيئة الافتراضية الخاصة بـ Qiskit من سطر الأوامر، ثم شغّل pip install jupyterlab (أو أيًا كانت واجهة الدفتر التي تستخدمها)، وأعد فتح Jupyter.

`import qiskit` ينجح، لكن أي محاولة للعمل ترجع "AttributeError: module 'qiskit' has no attribute '...'"

على الأرجح يعني هذا أن بيئتك كانت تحتوي على إصدار قديم من Qiskit إلى جانب حزمة مدّت فضاء أسمائه (مثل الإصدارات القديمة من Qiskit Aer، أو الـ Qiskit IBM Q® Provider القديم المتقادم)، ثم أُلغي تثبيت Qiskit. أسهل حل هو إنشاء بيئة افتراضية جديدة وتثبيت الحزم الحديثة غير المتقادمة فقط فيها.

إذا كنت قد أنشأت للتو بيئة افتراضية جديدة، أو كنت متأكدًا من أن الحزم القديمة ليست السبب، تحقق من أن مجلد العمل الحالي (المجلد الذي كانت جلسة الـ shell فيه حين أطلقت Python أو Jupyter) لا يحتوي على مجلد باسم qiskit. قواعد Python الافتراضية تبحث في مجلد العمل الحالي في وقت مبكر جدًا أثناء البحث في مسار التحميل عند محاولة import أي وحدة، لذا يمكن لمجلد بنفس الاسم أن يسبب مشكلات في الاستيراد.

`pip` يرفض تثبيت بعض الحزم معًا

بعد تشغيل أمر pip install مع عدة عناصر، قد تظهر رسالة خطأ كهذه:

ERROR: Cannot install qiskit-dynamics==0.4.4 and qiskit==1.0.0 because these package versions have conflicting dependencies.

The conflict is caused by:
    The user requested qiskit==1.0.0
    qiskit-dynamics 0.4.4 depends on qiskit<1.0

To fix this you could try to:
1. loosen the range of package versions you've specified
2. remove package versions to allow pip attempt to solve the dependency conflict

ERROR: ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/topics/dependency-resolution/#dealing-with-dependency-conflicts

هذا يصف تعارضًا حقيقيًا في الحل؛ لا توجد طريقة صالحة لتثبيت كل هذه التوزيعات معًا في آنٍ واحد.

في سياق Qiskit v1.0، على الأرجح أن أحد التوزيعات التي تحاول تثبيتها يحتوي على متطلب مثل qiskit<1.0. هذا يعني أن مطوري ذلك التوزيع قد وسموه بأنه غير متوافق (بعد) مع Qiskit v1.0.

يمكنك (بأسلوب مهذب) سؤال هؤلاء المطورين عن موعد إصدار نسخة جديدة من حزمتهم متوافقة مع Qiskit v1.0، لكن تحقق أولًا من عدم وجود issue أو pull request مفتوح يطلب ذلك في مكان التعليقات المعتمد لديهم. ضع في اعتبارك أن هذا يستغرق وقتًا؛ امنح المطورين شهرًا أو نحوه لإعداد إصدارات جديدة من توزيعاتهم! حتى ذلك الحين، لا يمكنك تثبيت ذلك التوزيع بجانب Qiskit v1.0. للاستمرار في استخدام ذلك التوزيع، أنشئ بيئة افتراضية جديدة واستخدم Qiskit 0.45 أو 0.46 (أو أيًا كان الإصدار الذي يدعمه) بجانب تلك الحزمة.

تنبيه

إذا واجهت هذا الخطأ، لا تحاول بناء البيئة عبر استدعاء pip install عدة مرات. على الأرجح لن تفشل تلك الأوامر، لكنك ستكون قد أنشأت بيئة غير صالحة. ومن المحتمل أنك ستواجه بعد ذلك بعض رسائل الخطأ الأخرى الموضحة في هذا القسم.

يمكنك أيضًا قراءة توثيق Python Packaging Authority حول حل التعارضات.

`pip` ينجح لكن يطبع أخطاءً بعد تشغيل أوامر `pip install`

قد تظهر في مخرجات pip رسالة خطأ كهذه:

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behavior is the source of the following dependency conflicts.
some-distribution 0.4.4 requires qiskit>=0.44,<1, but you have qiskit v1.0.0 which is incompatible.

السطر الأول يظهر عادةً حرفيًا (اعتبارًا من pip 23.3)، أما السطر الثاني فيتغير حسب المشكلة الدقيقة، وقد تكون هناك عدة أسطر مثله. من المحتمل أن يشير pip بعدها إلى أنه نفّذ ما أردت بنجاح رغم رسالة الخطأ.

هذا يعني أن البيئة في حالة تعارض ولا يمكنك الاطمئنان إلى أنها ستعمل بشكل صحيح. لحل المشكلة، افحص قائمة الرسائل الصادرة عن pip وحدد ما إذا كنت تحتاج فعلًا كل الحزم التي لديها متطلبات متعارضة. أحيانًا تكون هناك تعارضات حقيقية بين الاعتماديات؛ وقد تحتاج إلى بيئات افتراضية متعددة لفصل الاعتماديات ذات المتطلبات غير المتوافقة.

الخيار الأكثر أمانًا هو البدء ببيئة افتراضية جديدة (أو أكثر من واحدة إذا كانت هناك تعارضات حقيقية)، ثم حذف البيئة المتعارضة.

عند إعداد البيئات الافتراضية، شغّل أمر pip install واحدًا فقط يشمل جميع الاعتماديات التي تحتاجها. هذه هي الطريقة الأكثر موثوقية لكي يجد pip بيئة محلولة بشكل صحيح دون تعارضات. إذا استمرت مشكلات التعارض بعد إعداد البيئات، تجنّب تشغيل أي أوامر pip install أو pip uninstall إضافية؛ فـ pip لا يضمن الحفاظ على تماسك البيئة عند تشغيل أوامر لاحقة.

ملاحظة

إذا كنت قلقًا من التعامل مع بيئات افتراضية متعددة، اطمئن فالتطوير واستخدام Python كثيرًا ما يستلزم عدة بيئات افتراضية. إنشاء بيئات جديدة للعمل على مشاريع منفصلة أمر شائع وممارسة جيدة. حين تنتهي من بيئة افتراضية، يمكنك ببساطة حذف مجلدها؛ لا داعي للإبقاء على بيئات متعددة إلى الأبد.

`import qiskit` يرفع `ImportError`

عند تشغيل import qiskit، قد تظهر رسالة خطأ كهذه:

ImportError: Qiskit is installed in an invalid environment that has both Qiskit 1.0+ and an earlier version. You should create a new virtual environment, and ensure that you do not mix dependencies between Qiskit pre-1.0 and post-1.0. Any packages that depend on 'qiskit-terra' are not compatible with Qiskit 1.0 and will need to be updated. Qiskit unfortunately cannot enforce this requirement during environment resolution.

نصيحة

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

يعني الخطأ أن Qiskit مثبّت في بيئة غير صالحة تحتوي على كل من Qiskit v1.0 وإصدار سابق. ويتجلى ذلك في تواجد توزيعة qiskit-terra بجانب Qiskit v1.0. يمكنك الاطلاع على التوزيعات المثبّتة بتشغيل pip list، لكنك لا تستطيع إصلاح هذا بمجرد إلغاء تثبيت qiskit-terra.

للأسف، qiskit>=1.0 وqiskit-terra توزيعتان متعارضتان ولا يمكن تثبيتهما معًا. والأسوأ من ذلك أننا لا نستطيع إيصال هذا التعارض إلى pip بسبب قيود في نظام البيانات الوصفية الخاص به.

يحدث هذا الخطأ في الغالب في إحدى حالتين:

شغّلت شيئًا مثل pip install 'qiskit>=1' something-else، وsomething-else لديه متطلب على qiskit-terra.
حاولت تشغيل pip install -U qiskit في بيئة موجودة مسبقًا.

في كلتا الحالتين، لا يوجد ضمان بأن pip سيعطيك رسالة مفيدة.

نصيحة

إحدى طرق إجبار pip على منع qiskit-terra من أوامر install الفردية هي استخدام ملف قيود (constraints file) يشترط تعيين qiskit-terra على إصدار مستحيل. على سبيل المثال، ملف قيود يحتوي على السطر qiskit-terra>=1.0 سيعني أنه إذا حاولت اعتمادية تثبيت qiskit-terra، فلن تتطابق أي إصدارات منشورة مع المتطلبات.

لقد وفّرنا مثل هذا الملف في GitHub Gist على https://qisk.it/1-0-constraints، ويمكنك استخدامه هكذا:

pip install -c https://qisk.it/1-0-constraints qiskit [other packages]

إذا كانت إحدى الحزم تتطلب qiskit-terra، ستظهر لك رسالة فشل الحل.

إنشاء بيئة عمل صالحة لـ Qiskit v1.0

بصرف النظر عن كيف وصلت إلى هذا الوضع، فإن إنشاء بيئة افتراضية جديدة هو الأسهل بكثير.

أولًا، نحتاج معرفة الحزم التي تُضيف اعتمادية على qiskit-terra. باستخدام البيئة المعطوبة، ثبّت pipdeptree من PyPI. وهي أداة لتوليد رسوم بيانية للاعتماديات:

pip install pipdeptree

اسألها عن الحزم التي تُضيف اعتماديات على qiskit-terra وqiskit (هذان أمران منفصلان):

pipdeptree --reverse --package qiskit-terra

pipdeptree --reverse --package qiskit

قد تبدو المخرجات كالتالي:

qiskit-terra==0.45.2
└── qiskit-dynamics==0.4.2 [requires: qiskit-terra>=0.23.0]

qiskit==1.0.0
├── qiskit-aer==0.13.2 [requires: qiskit>=0.45.0]
└── qiskit-ibm-provider==0.8.0 [requires: qiskit>=0.45.0]

في المثال أعلاه، لدينا توزيعتان أعلنتا توافقهما مع Qiskit v1.0 (وهما qiskit-aer وqiskit-ibm-provider)، وتوزيعة واحدة لا تزال تعتمد على qiskit-terra.

نصيحة

هذا المثال يُمثّل هيكل اعتماديات مسطّحًا. قد ترى شجرة أعمق بكثير من هذا. الحزم المعتمدة مباشرةً على qiskit-terra (ذات المسافة البادئة الأقل) هي الأرجح أن تكون الإشكالية، لكن حزمة أعمق في الشجرة قد تكون مشكلة إذا كانت تعتمد على إصدار قديم محدد من حزمة أخرى سبق تحديثها.

وجود اعتمادية على qiskit-terra قد يعني أحد أمور عدة:

التوزيعة المعتمِدة حزمة قديمة ولن يُحدَّث لدعم Qiskit v1.0.

في هذه الحالة، لا فرصة لاستخدام الحزمة مع Qiskit v1.0، وستحتاج إلى الاستمرار في استخدام إصدار سابق من Qiskit. يتجلى هذا عادةً في كون التوزيعة المعتمِدة هي أحدث إصدار لها (بافتراض أن البيئة جديدة ولم تحدد إصدارًا أقل) وأن لديها متطلبًا مباشرًا على qiskit-terra.
التوزيعة المعتمِدة حزمة يُصانها فريق نشط، لكنها لا تدعم Qiskit v1.0 بعد.

في هذه الحالة، ستحتاج إلى انتظار المطورين لإصدار نسخة متوافقة - تحلّ بالصبر من فضلك! يتجلى هذا عادةً في كون التوزيعة المثبّتة ليست أحدث إصدار لها، على الرغم من أن أمر التثبيت لم يحدد إصدارًا بعينه. يمكنك التحقق من أحدث إصدار للتوزيعة بالبحث عن صفحتها على https://pypi.org/.

على الأرجح قام pip بالبحث في إصدارات قديمة من الحزمة حتى وجد واحدًا (ربما من أشهر أو سنوات مضت) يعتمد فقط على qiskit-terra.

هذا ما حدث في المثال أعلاه. في وقت إنشاء هذا المستند، كان qiskit-dynamics==0.4.4 هو أحدث إصدار.

إذا بنيت هذه البيئة من عدة أوامر pip install (كما لو كانت البيئة قديمة وجرى تحديثها)، حاول أولًا تثبيت جميع حزمك باستخدام أمر pip install واحد عند بناء بيئة جديدة. إذا استمرت المشكلة، فمن المرجح أن إحدى الحزم التي تريدها لا تدعم Qiskit v1.0 بعد، وpip يجد إصدارًا قديمًا يعتقد أنه سيعمل لأنه لا يعلم بتعارض qiskit>=1/qiskit-terra.

بدلًا من ذلك، استخدم أوامر pipdeptree لتحديد الاعتماديات التي لا تدعم Qiskit v1.0 بعد. استثنِ أي حزم لا تدعم Qiskit v1.0 بعد عند بناء بيئة Qiskit v1.0، أو استمر في استخدام إصدار سابق من Qiskit. راجع إنشاء البيئة الجديدة للتعليمات.

ملاحظة

المثال في هذا القسم أُنشئ قبل إصدار Qiskit v1.0.

التوزيعة "القديمة" المعنية (qiskit-dynamics) كانت تتصرف بشكل صحيح؛ لم يكن معروفًا أنها تدعم Qiskit v1.0 بعد، لذا أشارت إلى ذلك في متطلباتها. ليس من الممكن تعديل المتطلبات بأثر رجعي على الإصدارات المنشورة مسبقًا، وpip سيبحث بلا حدود للخلف للعثور على شيء يعمل عند بناء البيئة.

إنشاء بيئة عمل صالحة لـ Qiskit 0.45 أو 0.46

إذا كانت لديك بيئة معطوبة بعد محاولة تثبيت Qiskit 0.45 أو 0.46، فالأرجح أن pip قام بتثبيت Qiskit v1.0 لأنه حاول اختيار أحدث إصدار من الحزم، حتى وإن لم يكن مطلوبًا. أسهل طريقة لإصلاح هذا هي إنشاء بيئة افتراضية جديدة، ثم تشغيل أمر pip install واحد يشمل جميع الحزم التي تحتاجها، بالإضافة إلى إدخال صريح بـ 'qiskit<1'. إذا نجح pip في حل هذا الرسم البياني للاعتماديات، ستكون لديك بيئة افتراضية تعمل بشكل صحيح. إذا كانت إحدى التوزيعات تتطلب Qiskit v1.0 أو أحدث، فيجب أن يعطيك pip رسالة خطأ توضح ذلك، والتي تشبه الواردة في قسم الحلول الفاشلة.

يمكنك أيضًا استخدام أوامر pipdeptree المذكورة في إنشاء بيئة عمل صالحة لـ Qiskit v1.0 من داخل البيئة المعطوبة لتحديد التوزيعات التي لديها متطلب صريح على qiskit>=1.

أنا مطوّر، بيئاتي صحيحة بالتأكيد، ولا أزال أحصل على الخطأ

أولًا: يجب أن تكون متأكدًا تمامًا من صحة بيئاتك. الاختبار الذي يستخدمه Qiskit لتحديد البيئة المعطوبة قوي جدًا؛ تحديدًا، يستعلم من importlib.metadata للحصول على معلومات التوزيعة حول الحزم المثبّتة ويتحقق من أرقام الإصدارات المُعادة. كما يتحقق جانب Qiskit v1.0 من الاختبار من وجود ملفات مؤشر كانت موجودة في إصدارات Qiskit القديمة دون Qiskit v1.0.

إذا كنت مطوّرًا على Qiskit، فمن المحتمل أن لديك مجلدات qiskit.egg-info أو qiskit-terra.egg-info قديمة (أو *.dist-info) موجودة على مسار التعريف الخاص بك (انظر sys.meta_path)، تبقّت من تثبيتات قابلة للتعديل قديمة. تحقق على وجه الخصوص من مجلد العمل الخاص بك للبحث عن أي مجلدات *.egg-info و*.dist-info. إذا كانت في جذر أحد مستودعاتك المُسحوبة، يمكنك حذفها. أسوأ ما يمكن أن يحدث هو أنك قد تحتاج إلى تشغيل pip install -e . مجددًا، وحتى هذا مستبعد، لأن هذه المجلدات عادةً ما تكون جزءًا من عملية بناء setuptools التي لا يجري تنظيفها.

إذا لم تساعدك المعلومات أعلاه وأنت متأكد 100% من سلامة بيئتك (أو تحاول عمدًا اختبار بيئة معطوبة):

أنشئ issue في Qiskit موضّحًا كيف حدث هذا ولماذا أنت متأكد من صحة البيئة حتى نتمكن من إصلاحه.
يمكنك إسكات الاستثناء عن طريق تعيين متغير البيئة QISKIT_SUPPRESS_1_0_IMPORT_ERROR=1.

للمستخدمين​

إنشاء البيئة الجديدة​

استخدام البيئة الجديدة​

للمطوّرين​

التوصيات المتعلقة بالمتطلبات​

التوصيات المتعلقة بالاختبار مع Qiskit v1.0​

الترقية اليدوية لبيئة موجودة​

نماذج لسير عمل GitHub Actions اليدوية​

نموذج لإعداد tox​

استكشاف الأخطاء وإصلاحها​

import qiskit يعطي الخطأ "ModuleNotFoundError: No module named 'qiskit'"​

import qiskit ينجح، لكن أي محاولة للعمل ترجع "AttributeError: module 'qiskit' has no attribute '...'"​

pip يرفض تثبيت بعض الحزم معًا​

pip ينجح لكن يطبع أخطاءً بعد تشغيل أوامر pip install​

import qiskit يرفع ImportError​

إنشاء بيئة عمل صالحة لـ Qiskit v1.0​

إنشاء بيئة عمل صالحة لـ Qiskit 0.45 أو 0.46​

أنا مطوّر، بيئاتي صحيحة بالتأكيد، ولا أزال أحصل على الخطأ​

للمستخدمين

إنشاء البيئة الجديدة

استخدام البيئة الجديدة

للمطوّرين

التوصيات المتعلقة بالمتطلبات

التوصيات المتعلقة بالاختبار مع Qiskit v1.0

الترقية اليدوية لبيئة موجودة

نماذج لسير عمل GitHub Actions اليدوية

نموذج لإعداد `tox`

استكشاف الأخطاء وإصلاحها

`import qiskit` يعطي الخطأ "ModuleNotFoundError: No module named 'qiskit'"

`import qiskit` ينجح، لكن أي محاولة للعمل ترجع "AttributeError: module 'qiskit' has no attribute '...'"

`pip` يرفض تثبيت بعض الحزم معًا

`pip` ينجح لكن يطبع أخطاءً بعد تشغيل أوامر `pip install`

`import qiskit` يرفع `ImportError`

إنشاء بيئة عمل صالحة لـ Qiskit v1.0

إنشاء بيئة عمل صالحة لـ Qiskit 0.45 أو 0.46

أنا مطوّر، بيئاتي صحيحة بالتأكيد، ولا أزال أحصل على الخطأ