pipkin
=======
Tool for managing distribution packages for MicroPython and CircuitPython on target devices or in a local directory.
Supports `mip- and upip-compatible packages <https://docs.micropython.org/en/latest/reference/packages.html>`_,
and regular pip-compatible packages.
By default it prefers micrpython-lib packages at https://micropython.org/pi/v2/index.json. If the package is not
found there, then it turns to PyPI.
Unlike some of the package managers for MicroPython and CircuitPython, pipkin keeps a minimal set of package
metadata (trimmed .dist-info/METADATA and .dist-info/RECORD) next to the package itself, just like pip.
This enables straigthforward approach for uninstalling, listing and freezing.
When installing with ``--compile`` switch, pipkin uses suitable `mpy-cross` to compile the
py-files on the fly and transfers resulting mpy-files to the target.
Installation
--------------
``pip install pipkin``
Usage
-----
The basic structure of the command line is ``pipkin <target selection> <command> <command arguments>``.
For example:
* ``pipkin --port /dev/ttyACM0 install micropython-logging``
* ``pipkin --mount G:\lib install adafruit-circuitpython-ssd1306``
* ``pipkin --mount G:\lib install --compile adafruit-circuitpython-ssd1306``
* ``pipkin --dir my_project/lib install micropython-logging micropython-oled``
* ``pipkin --port COM5 uninstall micropython-logging micropython-oled``
* ``pipkin --port COM5 list --outdated``
If you have attached a single CircuitPython device (with its filesystem mounted as a disk) or
a single well known MicroPython device (eg. Raspberry Pi Pico), then you can omit the target selection
part:
* ``pipkin install adafruit-circuitpython-ssd1306``
pipkin -h
----------
::
usage: pipkin [-h] [-V] [-v | -q] [-p <port> | -m <path> | -d <path>] {install,uninstall,list,show,freeze,check,download,wheel,cache} ...
Tool for managing MicroPython and CircuitPython packages
general:
-h, --help Show this help message and exit
-V, --version Show program version and exit
-v, --verbose Show more details about the process
-q, --quiet Don't show non-error output
target selection (pick one or let pipkin autodetect the port or mount):
-p <port>, --port <port>
Serial port of the target device
-m <path>, --mount <path>
Mount point (volume, disk, drive) of the target device
-d <path>, --dir <path>
Directory in the local filesystem
commands:
Use "pipkin <command> -h" for usage help of a command
{install,uninstall,list,show,freeze,check,download,wheel,cache}
install Install packages.
uninstall Uninstall packages.
list List installed packages.
show Show information about one or more installed packages.
freeze Output installed packages in requirements format.
check Verify installed packages have compatible dependencies.
download Download packages.
wheel Build Wheel archives for your requirements and dependencies.
cache Inspect and manage pipkin cache.
pipkin install -h
------------------
::
usage: pipkin install [-h] [-r [<file> [<file> ...]]] [-c [<file> [<file> ...]]] [--no-deps] [--pre] [-i <url>] [--extra-index-url [<url> [<url> ...]]]
[--no-index] [--no-mp-org] [-f <url|file|dir>] [-U] [--upgrade-strategy <upgrade_strategy>] [--force-reinstall] [--compile]
[<spec> [<spec> ...]]
Installs upip or pip compatible distribution packages onto a MicroPython/CircuitPython device or into a local directory.
positional arguments:
<spec> Package specification, eg. 'micropython-os' or 'micropython-os>=0.6'
optional arguments:
-h, --help show this help message and exit
-U, --upgrade Upgrade all specified packages to the newest available version. The handling of dependencies depends on the upgrade-strategy used.
--upgrade-strategy <upgrade_strategy>
Determines how dependency upgrading should be handled [default: only-if-needed]. 'eager' - dependencies are upgraded regardless of
whether the currently installed version satisfies the requirements of the upgraded package(s). 'only-if-needed' - are upgraded only when
they do not satisfy the requirements of the upgraded package(s).
--force-reinstall Reinstall all packages even if they are already up-to-date.
--compile Compile and install mpy files.
package selection:
-r [<file> [<file> ...]], --requirement [<file> [<file> ...]]
Install from the given requirements file.
-c [<file> [<file> ...]], --constraint [<file> [<file> ...]]
Constrain versions using the given constraints file.
--no-deps Don't install package dependencies.
--pre Include pre-release and development versions. By default, pipkin only finds stable versions.
index selection:
-i <url>, --index-url <url>
Base URL of the Python Package Index (default https://pypi.org/simple).
--extra-index-url [<url> [<url> ...]]
Extra URLs of package indexes to use in addition to --index-url.
--no-index Ignore package index (only looking at --find-links URLs instead).
--no-mp-org Don't let micropython.org/pi override other indexes.
-f <url|file|dir>, --find-links <url|file|dir>
If a URL or path to an html file, then parse for links to archives such as sdist (.tar.gz) or wheel (.whl) files. If a local path or
file:// URL that's a directory, then look for archives in the directory listing.
Adafruit-Blinka and co
----------------------
`Adafruit-Blinka <https://pypi.org/project/Adafruit-Blinka/>`_ is a compatibility library which allows
running CircuitPython code with CPython. When publishing CircuitPython libraries at PyPI, Adafruit
and the community have so far targeted only CPython users, because tools for connecting PyPI with bare metal
CircuitPython did not exist (or because at the moment it is not clear how to publish wheels for Pythons
which can't run pip themselves). Therefore the CircuitPython libraries at PyPI usually have Adafruit-Blinka
dependency, which is not relevant (and would even cause problems) on bare metal CircuitPython devices.
pipkin's current approach is to have its proxy-index return dummy Adafruit-Blinka distribution, which contains
no modules and has no dependencies. This means when you're installing a library which depends on Adafruit-Blinka,
you'll get Blinka's .dist-info directory with METADATA and RECORD, but nothing else. Let's call it
an optimized build.
Dummies are returned for all dists, which are currently omitted by
`adafruit/circuitpython-build-tools <https://github.com/adafruit/circuitpython-build-tools/blob/de44a709f6287d2759df14c89707f2d8f5a026f5/circuitpython_build_tools/scripts/build_bundles.py#L42>`_
Current state and goals
-----------------------
Handling packages meant for upip, micropython.org/pi overrides and the problems outlined in the
previous section, all together make pipkin less elegant and slower than one would like. Still, this is just
a start. There are several optimizations possible within current approach. Also, PyPI, pip, wheel
and packaging standards are evolving -- in the future it may become easy to publish separate wheels
for MicroPython and/or CircuitPython and pip may become usable for "cross-installing" packages for
other platforms.
Even if clumsy at times, pipkin tries to be the proof-of-concept for demonstrating that even in
the world of MicroPython and CircuitPython, we could continue publishing standard sdists
and wheels on PyPI and re-use the familiar approach for package management. While introducing
new formats and distribution mechanisms have their benefits, we shouldn't dismiss the standard approach
yet.
Implementation
--------------
pipkin delegates most of its work to our old friend pip. This is the reason it is able to offer
so much functionality.
Both upip-compatibility and support for micropython.org-s
index is achieved by using up a temporary local index, which proxies both PyPI (or another specified index)
and micropython.org/pi and restores missing setup.py for upip-compatible packages.
Non-CPython installation target is achieved by creating and maintaining private working environment (venv).
(As creating a venv can be slow in Windows, be prepared for longer wait when using pipkin for the first time.)
In the beginning of the session, pipkin collects package metadata from the target (eg. from the /lib directory
of the device connected over serial) and creates corresponding dummy packages in the working environment.
Then it starts the temporary local index and invokes venv-s pip aginst it. When pip finishes, it detects the
distributions which are removed, added or changed and applies corresponding changes to the target device or
directory.
Raw data
{
"_id": null,
"home_page": "https://github.com/aivarannamaa/pipkin",
"name": "pipkin",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "MicroPython CircuitPython pip upip",
"author": "Aivar Annamaa",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/76/87/fb35009b19ee6e710f5cd883c9c24e6bd873eb9ebd2e228065c5ab5b71e0/pipkin-2.1b1.tar.gz",
"platform": "Windows",
"description": "pipkin\n=======\nTool for managing distribution packages for MicroPython and CircuitPython on target devices or in a local directory.\n\nSupports `mip- and upip-compatible packages <https://docs.micropython.org/en/latest/reference/packages.html>`_,\nand regular pip-compatible packages.\n\nBy default it prefers micrpython-lib packages at https://micropython.org/pi/v2/index.json. If the package is not\nfound there, then it turns to PyPI.\n\nUnlike some of the package managers for MicroPython and CircuitPython, pipkin keeps a minimal set of package\nmetadata (trimmed .dist-info/METADATA and .dist-info/RECORD) next to the package itself, just like pip.\nThis enables straigthforward approach for uninstalling, listing and freezing.\n\nWhen installing with ``--compile`` switch, pipkin uses suitable `mpy-cross` to compile the\npy-files on the fly and transfers resulting mpy-files to the target.\n\nInstallation\n--------------\n``pip install pipkin``\n\nUsage\n-----\n\nThe basic structure of the command line is ``pipkin <target selection> <command> <command arguments>``.\nFor example:\n\n* ``pipkin --port /dev/ttyACM0 install micropython-logging``\n* ``pipkin --mount G:\\lib install adafruit-circuitpython-ssd1306``\n* ``pipkin --mount G:\\lib install --compile adafruit-circuitpython-ssd1306``\n* ``pipkin --dir my_project/lib install micropython-logging micropython-oled``\n* ``pipkin --port COM5 uninstall micropython-logging micropython-oled``\n* ``pipkin --port COM5 list --outdated``\n\nIf you have attached a single CircuitPython device (with its filesystem mounted as a disk) or\na single well known MicroPython device (eg. Raspberry Pi Pico), then you can omit the target selection\npart:\n\n* ``pipkin install adafruit-circuitpython-ssd1306``\n\npipkin -h\n----------\n\n::\n\n usage: pipkin [-h] [-V] [-v | -q] [-p <port> | -m <path> | -d <path>] {install,uninstall,list,show,freeze,check,download,wheel,cache} ...\n\n Tool for managing MicroPython and CircuitPython packages\n\n general:\n -h, --help Show this help message and exit\n -V, --version Show program version and exit\n -v, --verbose Show more details about the process\n -q, --quiet Don't show non-error output\n\n target selection (pick one or let pipkin autodetect the port or mount):\n -p <port>, --port <port>\n Serial port of the target device\n -m <path>, --mount <path>\n Mount point (volume, disk, drive) of the target device\n -d <path>, --dir <path>\n Directory in the local filesystem\n\n commands:\n Use \"pipkin <command> -h\" for usage help of a command\n\n {install,uninstall,list,show,freeze,check,download,wheel,cache}\n install Install packages.\n uninstall Uninstall packages.\n list List installed packages.\n show Show information about one or more installed packages.\n freeze Output installed packages in requirements format.\n check Verify installed packages have compatible dependencies.\n download Download packages.\n wheel Build Wheel archives for your requirements and dependencies.\n cache Inspect and manage pipkin cache.\n\npipkin install -h\n------------------\n\n::\n\n usage: pipkin install [-h] [-r [<file> [<file> ...]]] [-c [<file> [<file> ...]]] [--no-deps] [--pre] [-i <url>] [--extra-index-url [<url> [<url> ...]]]\n [--no-index] [--no-mp-org] [-f <url|file|dir>] [-U] [--upgrade-strategy <upgrade_strategy>] [--force-reinstall] [--compile]\n [<spec> [<spec> ...]]\n\n Installs upip or pip compatible distribution packages onto a MicroPython/CircuitPython device or into a local directory.\n\n positional arguments:\n <spec> Package specification, eg. 'micropython-os' or 'micropython-os>=0.6'\n\n optional arguments:\n -h, --help show this help message and exit\n -U, --upgrade Upgrade all specified packages to the newest available version. The handling of dependencies depends on the upgrade-strategy used.\n --upgrade-strategy <upgrade_strategy>\n Determines how dependency upgrading should be handled [default: only-if-needed]. 'eager' - dependencies are upgraded regardless of\n whether the currently installed version satisfies the requirements of the upgraded package(s). 'only-if-needed' - are upgraded only when\n they do not satisfy the requirements of the upgraded package(s).\n --force-reinstall Reinstall all packages even if they are already up-to-date.\n --compile Compile and install mpy files.\n\n package selection:\n -r [<file> [<file> ...]], --requirement [<file> [<file> ...]]\n Install from the given requirements file.\n -c [<file> [<file> ...]], --constraint [<file> [<file> ...]]\n Constrain versions using the given constraints file.\n --no-deps Don't install package dependencies.\n --pre Include pre-release and development versions. By default, pipkin only finds stable versions.\n\n index selection:\n -i <url>, --index-url <url>\n Base URL of the Python Package Index (default https://pypi.org/simple).\n --extra-index-url [<url> [<url> ...]]\n Extra URLs of package indexes to use in addition to --index-url.\n --no-index Ignore package index (only looking at --find-links URLs instead).\n --no-mp-org Don't let micropython.org/pi override other indexes.\n -f <url|file|dir>, --find-links <url|file|dir>\n If a URL or path to an html file, then parse for links to archives such as sdist (.tar.gz) or wheel (.whl) files. If a local path or\n file:// URL that's a directory, then look for archives in the directory listing.\n\nAdafruit-Blinka and co\n----------------------\n`Adafruit-Blinka <https://pypi.org/project/Adafruit-Blinka/>`_ is a compatibility library which allows\nrunning CircuitPython code with CPython. When publishing CircuitPython libraries at PyPI, Adafruit\nand the community have so far targeted only CPython users, because tools for connecting PyPI with bare metal\nCircuitPython did not exist (or because at the moment it is not clear how to publish wheels for Pythons\nwhich can't run pip themselves). Therefore the CircuitPython libraries at PyPI usually have Adafruit-Blinka\ndependency, which is not relevant (and would even cause problems) on bare metal CircuitPython devices.\n\npipkin's current approach is to have its proxy-index return dummy Adafruit-Blinka distribution, which contains\nno modules and has no dependencies. This means when you're installing a library which depends on Adafruit-Blinka,\nyou'll get Blinka's .dist-info directory with METADATA and RECORD, but nothing else. Let's call it\nan optimized build.\n\nDummies are returned for all dists, which are currently omitted by\n`adafruit/circuitpython-build-tools <https://github.com/adafruit/circuitpython-build-tools/blob/de44a709f6287d2759df14c89707f2d8f5a026f5/circuitpython_build_tools/scripts/build_bundles.py#L42>`_\n\nCurrent state and goals\n-----------------------\nHandling packages meant for upip, micropython.org/pi overrides and the problems outlined in the\nprevious section, all together make pipkin less elegant and slower than one would like. Still, this is just\na start. There are several optimizations possible within current approach. Also, PyPI, pip, wheel\nand packaging standards are evolving -- in the future it may become easy to publish separate wheels\nfor MicroPython and/or CircuitPython and pip may become usable for \"cross-installing\" packages for\nother platforms.\n\nEven if clumsy at times, pipkin tries to be the proof-of-concept for demonstrating that even in\nthe world of MicroPython and CircuitPython, we could continue publishing standard sdists\nand wheels on PyPI and re-use the familiar approach for package management. While introducing\nnew formats and distribution mechanisms have their benefits, we shouldn't dismiss the standard approach\nyet.\n\nImplementation\n--------------\npipkin delegates most of its work to our old friend pip. This is the reason it is able to offer\nso much functionality.\n\nBoth upip-compatibility and support for micropython.org-s\nindex is achieved by using up a temporary local index, which proxies both PyPI (or another specified index)\nand micropython.org/pi and restores missing setup.py for upip-compatible packages.\n\nNon-CPython installation target is achieved by creating and maintaining private working environment (venv).\n(As creating a venv can be slow in Windows, be prepared for longer wait when using pipkin for the first time.)\n\nIn the beginning of the session, pipkin collects package metadata from the target (eg. from the /lib directory\nof the device connected over serial) and creates corresponding dummy packages in the working environment.\nThen it starts the temporary local index and invokes venv-s pip aginst it. When pip finishes, it detects the\ndistributions which are removed, added or changed and applies corresponding changes to the target device or\ndirectory.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Tool for installing packages for MicroPython and CircuitPython",
"version": "2.1b1",
"project_urls": {
"Bug tracker": "https://github.com/aivarannamaa/pipkin/issues",
"Homepage": "https://github.com/aivarannamaa/pipkin",
"Source code": "https://github.com/aivarannamaa/pipkin"
},
"split_keywords": [
"micropython",
"circuitpython",
"pip",
"upip"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7ac81364ae72d0465e6c346f334aa1e40622802638f4713e5b04350ab14d1351",
"md5": "4ad64f3db7c9d02dac1673c3d016c0b9",
"sha256": "66ddf98b8fe0dcfb7eb35ed959fb630315e4d3429e9049d22370fe7f42e077d6"
},
"downloads": -1,
"filename": "pipkin-2.1b1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4ad64f3db7c9d02dac1673c3d016c0b9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 46205,
"upload_time": "2024-03-31T15:36:45",
"upload_time_iso_8601": "2024-03-31T15:36:45.202812Z",
"url": "https://files.pythonhosted.org/packages/7a/c8/1364ae72d0465e6c346f334aa1e40622802638f4713e5b04350ab14d1351/pipkin-2.1b1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7687fb35009b19ee6e710f5cd883c9c24e6bd873eb9ebd2e228065c5ab5b71e0",
"md5": "0650aec6c49491f67b23ba43fe540923",
"sha256": "5cabfd4257f91e137e535caf7b467b809e63e00a4e304556a1c7863ec6ac2ca8"
},
"downloads": -1,
"filename": "pipkin-2.1b1.tar.gz",
"has_sig": false,
"md5_digest": "0650aec6c49491f67b23ba43fe540923",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 45706,
"upload_time": "2024-03-31T15:35:36",
"upload_time_iso_8601": "2024-03-31T15:35:36.480976Z",
"url": "https://files.pythonhosted.org/packages/76/87/fb35009b19ee6e710f5cd883c9c24e6bd873eb9ebd2e228065c5ab5b71e0/pipkin-2.1b1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-31 15:35:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aivarannamaa",
"github_project": "pipkin",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "pipkin"
}
JSON
