إدارة الحزم

تثبيت الحزم باستخدام mip

تتضمّن اللوحات القادرة على الاتصال بالشبكة الوحدة mip، التي يمكنها تثبيت الحزم من micropython-lib ومن مواقع الأطراف الثالثة (بما في ذلك GitHub و GitLab).

‏mip ("mip installs packages") مشابه من حيث المفهوم لأداة pip في Python، لكنه لا يستخدم فهرس PyPI، بل يستخدم micropython-lib كفهرس له افتراضيًا. وسيجلب mip تلقائيًا ملف .mpy file المُصرَّف عند التنزيل من micropython-lib.

الطريقة الأكثر شيوعًا لاستخدام mip هي من الـ REPL:

>>> import mip
>>> mip.install("pkgname")  # Installs the latest version of "pkgname" (and dependencies)
>>> mip.install("pkgname", version="x.y")  # Installs version x.y of "pkgname"
>>> mip.install("pkgname", mpy=False)  # Installs the source version (i.e. .py rather than .mpy files)

سيكتشف mip موقعًا مناسبًا في نظام الملفات بالبحث في sys.path عن أول مدخل ينتهي بـ /lib. يمكنك تجاوز الوجهة باستخدام target، لكن لاحظ أن هذا المسار يجب أن يكون في sys.path لتتمكن لاحقًا من استيراده:

>>> mip.install("pkgname", target="third-party")
>>> sys.path.append("third-party")

إلى جانب تنزيل الحزم من فهرس micropython-lib، يمكن لـ mip أيضًا تثبيت مكتبات الأطراف الثالثة. وأبسط طريقة هي تنزيل ملف مباشرةً:

>>> mip.install("http://example.com/x/y/foo.py")
>>> mip.install("http://example.com/x/y/foo.mpy")

عند تثبيت ملف مباشرةً، لا يزال الوسيط target مدعومًا لضبط مسار الوجهة، لكن يُتجاهل mpy و version.

يمكن أيضًا أن يبدأ عنوان URL بـ github: أو gitlab: كطريقة بسيطة للإشارة إلى محتوى مستضاف على GitHub أو GitLab:

>>> mip.install("github:org/repo/path/foo.py")  # Uses default branch
>>> mip.install("github:org/repo/path/foo.py", version="branch-or-tag")  # Optionally specify the branch or tag
>>> mip.install("gitlab:org/repo/path/foo.py")  # Uses default branch
>>> mip.install("gitlab:org/repo/path/foo.py", version="branch-or-tag")  # Optionally specify the branch or tag

يمكن تنزيل الحزم الأكثر تطورًا (أي التي تحتوي على أكثر من ملف، أو لها اعتماديات) بتحديد المسار إلى ملف package.json الخاص بها:

>>> mip.install("http://example.com/x/package.json")
>>> mip.install("github:org/user/path/package.json")
>>> mip.install("gitlab:org/user/path/package.json")

إذا لم يُحدَّد ملف json، فإن "package.json" يُضاف ضمنيًا:

>>> mip.install("http://example.com/x/")
>>> mip.install("github:org/repo")  # Uses default branch of that repo
>>> mip.install("github:org/repo", version="branch-or-tag")
>>> mip.install("gitlab:org/repo")  # Uses default branch of that repo
>>> mip.install("gitlab:org/repo", version="branch-or-tag")

استخدام mip على منفذ Unix

على منفذ Unix، يمكن استخدام mip في الـ REPL كما هو موضح أعلاه، وكذلك باستخدام -m

$ ./micropython -m mip install pkgname-or-url
$ ./micropython -m mip install pkgname-or-url@version

يمكن ضبط الوسائط --target path و --no-mpy و --index

$ ./micropython -m mip install --target third-party pkgname
$ ./micropython -m mip install --no-mpy pkgname
$ ./micropython -m mip install --index https://host/pi pkgname

تثبيت الحزم باستخدام mpremote

تتضمّن أداة mpremote أيضًا نفس وظائف mip ويمكن استخدامها من حاسوب مضيف لتثبيت الحزم على جهاز متصل محليًا (مثلًا عبر USB أو UART):

$ mpremote mip install pkgname
$ mpremote mip install [email protected]
$ mpremote mip install http://example.com/x/y/foo.py
$ mpremote mip install github:org/repo
$ mpremote mip install github:org/repo@branch-or-tag
$ mpremote mip install gitlab:org/repo
$ mpremote mip install gitlab:org/repo@branch-or-tag

يمكن ضبط الوسائط --target=path و --no-mpy و --index

$ mpremote mip install --target=/flash/third-party pkgname
$ mpremote mip install --no-mpy pkgname
$ mpremote mip install --index https://host/pi pkgname

يمكن لـ mpremote أيضًا تثبيت الحزم من ملفات مخزّنة على نظام الملفات المحلي للمضيف:

$ mpremote mip install path/to/pkg.py
$ mpremote mip install path/to/app/package.json
$ mpremote mip install \\path\\to\\pkg.py

هذا مفيد بشكل خاص لاختبار الحزم أثناء التطوير ولتثبيت الحزم من نسخ محلية لمستودعات GitHub. لاحظ أن عناوين URL في ملفات package.json يجب أن تستخدم الشرطة المائلة الأمامية ("/") كفواصل للأدلة، حتى على Windows، حتى تكون متوافقة مع التثبيت من الويب.

تثبيت الحزم يدويًا

يمكن أيضًا تثبيت الحزم (بصيغة ‎.py‎ أو ‎.mpy‎) بنسخ الملفات يدويًا إلى الجهاز. وبحسب اللوحة قد يكون ذلك عبر التخزين الكتلي عبر USB، أو أداة mpremote (مثلًا mpremote fs cp path/to/package.py :package.py)، أو webrepl، إلخ.

كتابة الحزم ونشرها

النشر إلى micropython-lib هو أسهل طريقة لجعل حزمتك متاحة على نطاق واسع لمستخدمي MicroPython، ومتاحة تلقائيًا عبر mip و mpremote ومُصرَّفة إلى شيفرة بايت. انظر https://github.com/micropython/micropython-lib لمزيد من المعلومات.

لكتابة حزمة "ذاتية الاستضافة" يمكن تنزيلها عبر mip أو mpremote، تحتاج إلى خادم ويب ثابت (أو GitHub) لاستضافة إما ملف ‎.py‎ واحد، أو ملف package.json إلى جانب ملفات ‎.py‎ الخاصة بك.

مثال على مكتبة mlx90640 مستضافة على GitHub يمكن تثبيتها عبر:

$ mpremote mip install github:org/micropython-mlx90640

قد يبدو تخطيط الحزمة على GitHub كما يلي:

https://github.com/org/micropython-mlx90640/
    package.json
    mlx90640/
        __init__.py
        utils.py

يحدد package.json موقع الملفات المراد تثبيتها والاعتماديات الأخرى:

{
  "urls": [
    ["mlx90640/__init__.py", "mlx90640/__init__.py"],
    ["mlx90640/utils.py", "mlx90640/utils.py"]
  ],
  "deps": [
    ["collections-defaultdict", "latest"],
    ["os-path", "latest"],
    ["github:org/micropython-additions", "main"],
    ["gitlab:org/micropython-otheradditions", "main"]
  ],
  "version": "0.2"
}

تحدد قائمة urls الملفات المراد تثبيتها وفقًا لما يلي:

"urls": [
    [destination_path, source_url]
    ...

حيث destination_path هو موقع واسم الملف المراد تثبيته على الجهاز و source_url هو عنوان URL للملف المراد تثبيته. وعادةً يُحدَّد عنوان URL المصدر نسبةً إلى الدليل الذي يحتوي على ملف package.json، لكن يمكن أن يكون أيضًا عنوان URL مطلقًا، مثلًا:

["mlx90640/utils.py", "github:org/micropython-mlx90640/mlx90640/utils.py"]

تعتمد الحزمة على collections-defaultdict و os-path اللذين سيُثبَّتان تلقائيًا من micropython-lib. أما الاعتمادية الثالثة فتثبّت المحتوى كما هو محدد بواسطة ملف package.json للفرع main من مستودع GitHub المسمى org/micropython-additions.

تجميد الحزم

عند استيراد وحدة أو حزمة Python من نظام ملفات الجهاز، تُصرَّف إلى bytecode في ذاكرة RAM، جاهزةً للتنفيذ بواسطة الآلة الافتراضية (VM). وبالنسبة لملف .mpy file، يكون هذا التحويل قد تمّ بالفعل، لكن شيفرة البايت لا تزال تنتهي في ذاكرة RAM.

بالنسبة للأجهزة ذات الذاكرة المنخفضة، أو للتطبيقات الكبيرة، قد يكون من المفيد تشغيل شيفرة البايت من ذاكرة ROM (أي ذاكرة الفلاش) بدلًا من ذلك. ويمكن فعل ذلك بـ "تجميد" شيفرة البايت داخل البرنامج الثابت لـ MicroPython، الذي يُكتب بعد ذلك إلى الجهاز. ويبقى أداء وقت التشغيل كما هو (وإن كان الاستيراد أسرع)، لكنه يمكن أن يحرّر قدرًا كبيرًا من ذاكرة RAM ليستخدمها برنامجك.

الجانب السلبي لهذا النهج هو أن التطوير يصبح أبطأ بكثير، لأنه يتعيّن عليك كتابة البرنامج الثابت في كل مرة، لكنه لا يزال مفيدًا لتجميد الاعتماديات التي لا تتغير كثيرًا.

يُجرى التجميد بكتابة ملف بيان (manifest) واستخدامه في البناء، غالبًا كجزء من تعريف لوحة مخصص. انظر دليل ملفات بيان (manifest) في MicroPython لمزيد من المعلومات.