Správa balíčků¶

Instalace balíčků pomocí `mip`¶

Desky s podporou sítě obsahují modul mip, který umí instalovat balíčky z micropython-lib a z webů třetích stran (včetně GitHubu a GitLabu).

mip („mip installs packages“) je koncepčně podobný nástroji pip z Pythonu, nepoužívá však index PyPI, nýbrž ve výchozím nastavení používá jako svůj index micropython-lib. Při stahování z micropython-lib bude mip automaticky stahovat zkompilovaný .mpy file.

Nejběžnějším způsobem použití mip je z 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 zjistí vhodné umístění v souborovém systému tak, že prohledá sys.path a najde první položku končící na /lib. Cíl můžete přepsat pomocí target, ale uvědomte si, že tato cesta musí být v sys.path, aby bylo možné balíček následně importovat:

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

Kromě stahování balíčků z indexu micropython-lib umí mip instalovat také knihovny třetích stran. Nejjednodušší způsob je stáhnout soubor přímo:

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

Při přímé instalaci souboru je argument target stále podporován pro nastavení cílové cesty, ale mpy a version se ignorují.

URL může také začínat na github: nebo gitlab: jako jednoduchý způsob, jak odkázat na obsah hostovaný na GitHubu nebo GitLabu:

>>> 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

Sofistikovanější balíčky (tj. s více než jedním souborem nebo se závislostmi) lze stáhnout zadáním cesty k jejich 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")

Pokud není zadán žádný soubor json, pak se implicitně doplní „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")

Použití `mip` na portu Unix¶

Na portu Unix lze mip použít v REPL jako výše a také pomocí -m

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

Lze nastavit argumenty --target path, --no-mpy a --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

Instalace balíčků pomocí `mpremote`¶

Nástroj mpremote rovněž obsahuje tutéž funkcionalitu jako mip a lze jej použít z hostitelského PC k instalaci balíčků do lokálně připojeného zařízení (např. přes USB nebo 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

Lze nastavit argumenty --target=path, --no-mpy a --index

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

mpremote umí také instalovat balíčky ze souborů uložených v lokálním souborovém systému hostitele:

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

To je obzvláště užitečné pro testování balíčků během vývoje a pro instalaci balíčků z lokálních klonů GitHub repozitářů. Všimněte si, že URL v souborech package.json musí jako oddělovače adresářů používat lomítka („/“), a to i ve Windows, aby byly kompatibilní s instalací z webu.

Ruční instalace balíčků¶

Balíčky lze instalovat (buď ve formě .py, nebo .mpy) také ručním zkopírováním souborů do zařízení. V závislosti na desce to může být přes USB Mass Storage, nástrojem mpremote (např. mpremote fs cp path/to/package.py :package.py), pomocí webrepl atd.

Psaní a publikování balíčků¶

Publikování do micropython-lib je nejsnazší způsob, jak svůj balíček zpřístupnit širokému okruhu uživatelů MicroPythonu, a automaticky jej zpřístupnit přes mip a mpremote a zkompilovat do bytecode. Více informací viz https://github.com/micropython/micropython-lib.

Chcete-li napsat „self-hosted“ balíček, který lze stáhnout pomocí mip nebo mpremote, potřebujete statický webový server (nebo GitHub), který bude hostovat buď jeden soubor .py, nebo soubor package.json vedle vašich souborů .py.

Příklad knihovny mlx90640 hostované na GitHubu by bylo možné nainstalovat pomocí:

$ mpremote mip install github:org/micropython-mlx90640

Rozvržení balíčku na GitHubu by mohlo vypadat takto:

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

Soubor package.json určuje umístění souborů, které se mají nainstalovat, a další závislosti:

{
  "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"
}

Seznam urls určuje soubory k instalaci podle:

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

kde destination_path je umístění a název souboru, který se má nainstalovat na zařízení, a source_url je URL souboru, který se má nainstalovat. Zdrojová URL se obvykle uvádí relativně vůči adresáři obsahujícímu soubor package.json, ale může to být i absolutní URL, např.:

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

Balíček závisí na collections-defaultdict a os-path, které se automaticky nainstalují z micropython-lib. Třetí závislost nainstaluje obsah definovaný souborem package.json větve main GitHub repozitáře org/micropython-additions.

Zmrazování balíčků (freezing)¶

Když se modul nebo balíček Pythonu importuje ze souborového systému zařízení, zkompiluje se v RAM do bytecode, připravený k provedení virtuálním strojem (VM). U .mpy file už byl tento převod proveden, ale bytecode přesto skončí v RAM.

U zařízení s malou pamětí nebo u velkých aplikací může být výhodné místo toho spouštět bytecode z ROM (tj. z flash paměti). To lze provést „zmrazením“ (freezing) bytecode do firmwaru MicroPythonu, který se pak nahraje do zařízení. Výkon za běhu je stejný (i když import je rychlejší), ale lze tím uvolnit značné množství RAM pro váš program.

Nevýhodou tohoto přístupu je, že vývoj je mnohem pomalejší, protože musíte pokaždé nahrát firmware, ale stále může být užitečné zmrazit závislosti, které se příliš často nemění.

Zmrazování se provádí napsáním souboru manifestu a jeho použitím při sestavení, často jako součást vlastní definice desky. Více informací viz příručka Soubory manifestu MicroPython.