CircUp
======
.. image:: https://readthedocs.org/projects/circup/badge/?version=latest
:target: https://circuitpython.readthedocs.io/projects/circup/en/latest/
:alt: Documentation Status
.. image:: https://img.shields.io/discord/327254708534116352.svg
:target: https://adafru.it/discord
:alt: Discord
.. image:: https://github.com/adafruit/circup/workflows/Build%20CI/badge.svg
:target: https://github.com/adafruit/circup/actions
:alt: Build Status
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
:alt: Code Style: Black
A tool to manage and update libraries (modules) on a CircuitPython device.
.. contents::
Installation
------------
Circup requires Python 3.5 or higher.
In a `virtualenv <https://virtualenv.pypa.io/en/latest/>`_,
``pip install circup`` should do the trick. This is the simplest way to make it
work.
If you have no idea what a virtualenv is, try the following command,
``pip3 install --user circup``.
.. note::
If you use the ``pip3`` command to install CircUp you must make sure that
your path contains the directory into which the script will be installed.
To discover this path,
* On Unix-like systems, type ``python3 -m site --user-base`` and append
``bin`` to the resulting path.
* On Windows, type the same command, but append ``Scripts`` to the
resulting path.
What does Circup Do?
--------------------
Each CircuitPython library on the device usually has a version number as
metadata within the module.
This utility looks at all the libraries on the device and checks if they are
the most recent (compared to the versions found in the most recent version of
the Adafruit CircuitPython Bundle and Circuitpython Community Bundle). If the libraries are out of date, the
utility helps you update them.
The Adafruit CircuitPython Bundle can be found here:
https://github.com/adafruit/Adafruit_CircuitPython_Bundle/releases/latest
Full details of these libraries, what they're for and how to get them, can be
found here:
https://circuitpython.org/libraries
The Circuitpython Community Bundle can be found here:
https://github.com/adafruit/CircuitPython_Community_Bundle/releases/latest
Usage
-----
If you need more detailed help using Circup see the Learn Guide article
`"Use CircUp to easily keep your CircuitPython libraries up to date" <https://learn.adafruit.com/keep-your-circuitpython-libraries-on-devices-up-to-date-with-circup/>`_.
First, plug in a device running CircuiPython. This should appear as a mounted
storage device called ``CIRCUITPY``.
To get help, just type the command::
$ circup
Usage: circup [OPTIONS] COMMAND [ARGS]...
A tool to manage and update libraries on a CircuitPython device.
Options:
--verbose Comprehensive logging is sent to stdout.
--path DIRECTORY Path to CircuitPython directory. Overrides automatic
path detection.
--host TEXT Hostname or IP address of a device. Overrides automatic
path detection.
--password TEXT Password to use for authentication when --host is used.
--timeout INTEGER Specify the timeout in seconds for any network
operations.
--board-id TEXT Manual Board ID of the CircuitPython device. If provided
in combination with --cpy-version, it overrides the
detected board ID.
--cpy-version TEXT Manual CircuitPython version. If provided in combination
with --board-id, it overrides the detected CPy version.
--version Show the version and exit.
--help Show this message and exit.
Commands:
bundle-add Add bundles to the local bundles list, by "user/repo"...
bundle-remove Remove one or more bundles from the local bundles list.
bundle-show Show the list of bundles, default and local, with URL,...
example Copy named example(s) from a bundle onto the device.
freeze Output details of all the modules found on the connected...
install Install a named module(s) onto the device.
list Lists all out of date modules found on the connected...
show Show a list of available modules in the bundle.
uninstall Uninstall a named module(s) from the connected device.
update Update modules on the device. Use --all to automatically
update all modules without Major Version warnings.
To automatically install all modules imported by ``code.py``,
:code:`$ circup install --auto`::
$ circup install --auto
Found device at /Volumes/CIRCUITPY, running CircuitPython 7.0.0-alpha.5.
Searching for dependencies for: ['adafruit_bmp280']
Ready to install: ['adafruit_bmp280', 'adafruit_bus_device', 'adafruit_register']
Installed 'adafruit_bmp280'.
Installed 'adafruit_bus_device'.
Installed 'adafruit_register'.
To search for a specific module containing the name bme:
:code:`$ circup show bme`::
$ circup show bme
Found device at /Volumes/CIRCUITPY, running CircuitPython 6.1.0-beta.2.
adafruit_bme280
adafruit_bme680
2 shown of 257 packages.
To show version information for all the modules currently on a connected
CIRCUITPYTHON device::
$ circup freeze
adafruit_binascii==v1.0
adafruit_bme280==2.3.1
adafruit_ble==1.0.2
With :code:`$ circup freeze -r`, Circup will save, in the current working directory,
a requirements.txt file with a list of all modules currently installed on the
connected device.
To list all the modules that require an update::
$ circup list
The following modules are out of date or probably need an update.
Module Version Latest
------------------ -------- --------
adafruit_binascii v1.0 1.0.1
adafruit_ble 1.0.2 4.0
To interactively update the out-of-date modules::
$ circup update
Found 3 module[s] needing update.
Please indicate which modules you wish to update:
Update 'adafruit_binascii'? [y/N]: Y
OK
Update 'adafruit_ble'? [y/N]: Y
OK
Install a module or modules onto the connected device with::
$ circup install adafruit_thermal_printer
Installed 'adafruit_thermal_printer'.
$ circup install adafruit_thermal_printer adafruit_bus_io
Installed 'adafruit_thermal_printer'.
Installed 'adafruit_bus_io'.
If you need to work with the original .py version of a module, use the --py
flag.
$ circup install --py adafruit_thermal_printer
Installed 'adafruit_thermal_printer'.
You can also install a list of modules from a requirements.txt file in
the current working directory with::
$ circup install -r requirements.txt
Installed 'adafruit_bmp280'.
Installed 'adafruit_lis3mdl'.
Installed 'adafruit_lsm6ds'.
Installed 'adafruit_sht31d'.
Installed 'neopixel'.
Uninstall a module or modules like this::
$ circup uninstall adafruit_thermal_printer
Uninstalled 'adafruit_thermal_printer'.
$ circup uninstall adafruit_thermal_printer adafruit_bus_io
Uninstalled 'adafruit_thermal_printer'.
Uninstalled 'adafruit_bus_io'.
Use the ``--verbose`` flag to see the logs as the command is working::
$ circup --verbose freeze
Logging to /home/ntoll/.cache/circup/log/circup.log
10/18/2020 00:54:43 INFO: ### Started Circup ###
10/18/2020 00:54:43 INFO: Found device: /Volumes/CIRCUITPY
Found device at /Volumes/CIRCUITPY, running CircuitPython 6.0.0-alpha.1-1352-gf0b37313c.
10/18/2020 00:54:44 INFO: Freeze
10/18/2020 00:54:44 INFO: Found device: /Volumes/CIRCUITPY
... etc ...
The ``--path`` flag let's you pass in a different path to the CircuitPython
mounted volume. This is helpful when you have renamed or have more than one
CircuitPython devices attached::
$ circup --path /run/media/user/CIRCUITPY1 list
The ``--version`` flag will tell you the current version of the
``circup`` command itself::
$ circup --version
CircUp, A CircuitPython module updater. Version 0.0.1
To use circup via the `Web Workflow <https://learn.adafruit.com/getting-started-with-web-workflow-using-the-code-editor>`_. on devices that support it. Use the ``--host`` and ``--password`` arguments before your circup command.::
$ circup --host 192.168.1.119 --password s3cr3t install adafruit_hid
$ circup --host cpy-9573b2.local --password s3cr3t install adafruit_hid
That's it!
Library Name Autocomplete
-------------------------
When enabled, circup will autocomplete library names, simliar to other command line tools.
For example:
``circup install n`` + tab -``circup install neopixel`` (+tab: offers ``neopixel`` and ``neopixel_spi`` completions)
``circup install a`` + tab -``circup install adafruit\_`` + m a g + tab -``circup install adafruit_magtag``
How to Activate Library Name Autocomplete
-----------------------------------------
In order to activate shell completion, you need to inform your shell that completion is available for your script. Any Click application automatically provides support for that.
For Bash, add this to ~/.bashrc::
eval "$(_CIRCUP_COMPLETE=bash_source circup)"
For Zsh, add this to ~/.zshrc::
eval "$(_CIRCUP_COMPLETE=zsh_source circup)"
For Fish, add this to ~/.config/fish/completions/foo-bar.fish::
eval (env _CIRCUP_COMPLETE=fish_source circup)
Open a new shell to enable completion. Or run the eval command directly in your current shell to enable it temporarily.
### Activation Script
The above eval examples will invoke your application every time a shell is started. This may slow down shell startup time significantly.
Alternatively, export the generated completion code as a static script to be executed. You can ship this file with your builds; tools like Git do this. At least Zsh will also cache the results of completion files, but not eval scripts.
For Bash::
_CIRCUP_COMPLETE=bash_source circup circup-complete.sh
For Zsh::
_CIRCUP_COMPLETE=zsh_source circup circup-complete.sh
For Fish::
_CIRCUP_COMPLETE=fish_source circup circup-complete.sh
In .bashrc or .zshrc, source the script instead of the eval command::
. /path/to/circup-complete.sh
For Fish, add the file to the completions directory::
_CIRCUP_COMPLETE=fish_source circup ~/.config/fish/completions/circup-complete.fish
.. note::
If you find a bug, or you want to suggest an enhancement or new feature
feel free to create an issue or submit a pull request here:
https://github.com/adafruit/circup
Discussion of this tool happens on the Adafruit CircuitPython
`Discord channel <https://discord.gg/rqrKDjU>`_.
Raw data
{
"_id": null,
"home_page": "https://github.com/adafruit/circup",
"name": "circup",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "adafruit, blinka, circuitpython, micropython, libraries",
"author": "Adafruit Industries",
"author_email": "circuitpython@adafruit.com",
"download_url": "https://files.pythonhosted.org/packages/7c/ce/8ff82df705b2a6ea5cbbdabb95b55e7411acdea4a9edf2db873b5cfc4950/circup-1.8.0.tar.gz",
"platform": null,
"description": "\nCircUp\n======\n\n.. image:: https://readthedocs.org/projects/circup/badge/?version=latest\n :target: https://circuitpython.readthedocs.io/projects/circup/en/latest/\n :alt: Documentation Status\n\n.. image:: https://img.shields.io/discord/327254708534116352.svg\n :target: https://adafru.it/discord\n :alt: Discord\n\n\n.. image:: https://github.com/adafruit/circup/workflows/Build%20CI/badge.svg\n :target: https://github.com/adafruit/circup/actions\n :alt: Build Status\n\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n :alt: Code Style: Black\n\n\nA tool to manage and update libraries (modules) on a CircuitPython device.\n\n.. contents::\n\nInstallation\n------------\n\nCircup requires Python 3.5 or higher.\n\nIn a `virtualenv <https://virtualenv.pypa.io/en/latest/>`_,\n``pip install circup`` should do the trick. This is the simplest way to make it\nwork.\n\nIf you have no idea what a virtualenv is, try the following command,\n``pip3 install --user circup``.\n\n.. note::\n\n If you use the ``pip3`` command to install CircUp you must make sure that\n your path contains the directory into which the script will be installed.\n To discover this path,\n\n * On Unix-like systems, type ``python3 -m site --user-base`` and append\n ``bin`` to the resulting path.\n * On Windows, type the same command, but append ``Scripts`` to the\n resulting path.\n\nWhat does Circup Do?\n--------------------\n\nEach CircuitPython library on the device usually has a version number as\nmetadata within the module.\n\nThis utility looks at all the libraries on the device and checks if they are\nthe most recent (compared to the versions found in the most recent version of\nthe Adafruit CircuitPython Bundle and Circuitpython Community Bundle). If the libraries are out of date, the\nutility helps you update them.\n\nThe Adafruit CircuitPython Bundle can be found here:\n\nhttps://github.com/adafruit/Adafruit_CircuitPython_Bundle/releases/latest\n\nFull details of these libraries, what they're for and how to get them, can be\nfound here:\n\nhttps://circuitpython.org/libraries\n\nThe Circuitpython Community Bundle can be found here:\n\nhttps://github.com/adafruit/CircuitPython_Community_Bundle/releases/latest\n\nUsage\n-----\n\nIf you need more detailed help using Circup see the Learn Guide article\n`\"Use CircUp to easily keep your CircuitPython libraries up to date\" <https://learn.adafruit.com/keep-your-circuitpython-libraries-on-devices-up-to-date-with-circup/>`_.\n\nFirst, plug in a device running CircuiPython. This should appear as a mounted\nstorage device called ``CIRCUITPY``.\n\nTo get help, just type the command::\n\n $ circup\n Usage: circup [OPTIONS] COMMAND [ARGS]...\n\n A tool to manage and update libraries on a CircuitPython device.\n\n Options:\n --verbose Comprehensive logging is sent to stdout.\n --path DIRECTORY Path to CircuitPython directory. Overrides automatic\n path detection.\n --host TEXT Hostname or IP address of a device. Overrides automatic\n path detection.\n --password TEXT Password to use for authentication when --host is used.\n --timeout INTEGER Specify the timeout in seconds for any network\n operations.\n --board-id TEXT Manual Board ID of the CircuitPython device. If provided\n in combination with --cpy-version, it overrides the\n detected board ID.\n --cpy-version TEXT Manual CircuitPython version. If provided in combination\n with --board-id, it overrides the detected CPy version.\n --version Show the version and exit.\n --help Show this message and exit.\n\n Commands:\n bundle-add Add bundles to the local bundles list, by \"user/repo\"...\n bundle-remove Remove one or more bundles from the local bundles list.\n bundle-show Show the list of bundles, default and local, with URL,...\n example Copy named example(s) from a bundle onto the device.\n freeze Output details of all the modules found on the connected...\n install Install a named module(s) onto the device.\n list Lists all out of date modules found on the connected...\n show Show a list of available modules in the bundle.\n uninstall Uninstall a named module(s) from the connected device.\n update Update modules on the device. Use --all to automatically\n update all modules without Major Version warnings.\n\n\n\nTo automatically install all modules imported by ``code.py``,\n:code:`$ circup install --auto`::\n\n $ circup install --auto\n Found device at /Volumes/CIRCUITPY, running CircuitPython 7.0.0-alpha.5.\n Searching for dependencies for: ['adafruit_bmp280']\n Ready to install: ['adafruit_bmp280', 'adafruit_bus_device', 'adafruit_register']\n\n Installed 'adafruit_bmp280'.\n Installed 'adafruit_bus_device'.\n Installed 'adafruit_register'.\n\nTo search for a specific module containing the name bme:\n:code:`$ circup show bme`::\n\n $ circup show bme\n Found device at /Volumes/CIRCUITPY, running CircuitPython 6.1.0-beta.2.\n adafruit_bme280\n adafruit_bme680\n 2 shown of 257 packages.\n\nTo show version information for all the modules currently on a connected\nCIRCUITPYTHON device::\n\n $ circup freeze\n adafruit_binascii==v1.0\n adafruit_bme280==2.3.1\n adafruit_ble==1.0.2\n\nWith :code:`$ circup freeze -r`, Circup will save, in the current working directory,\na requirements.txt file with a list of all modules currently installed on the\nconnected device.\n\nTo list all the modules that require an update::\n\n $ circup list\n The following modules are out of date or probably need an update.\n\n Module Version Latest\n ------------------ -------- --------\n adafruit_binascii v1.0 1.0.1\n adafruit_ble 1.0.2 4.0\n\nTo interactively update the out-of-date modules::\n\n $ circup update\n Found 3 module[s] needing update.\n Please indicate which modules you wish to update:\n\n Update 'adafruit_binascii'? [y/N]: Y\n OK\n Update 'adafruit_ble'? [y/N]: Y\n OK\n\nInstall a module or modules onto the connected device with::\n\n $ circup install adafruit_thermal_printer\n Installed 'adafruit_thermal_printer'.\n\n $ circup install adafruit_thermal_printer adafruit_bus_io\n Installed 'adafruit_thermal_printer'.\n Installed 'adafruit_bus_io'.\n\nIf you need to work with the original .py version of a module, use the --py\nflag.\n\n $ circup install --py adafruit_thermal_printer\n Installed 'adafruit_thermal_printer'.\n\nYou can also install a list of modules from a requirements.txt file in\nthe current working directory with::\n\n $ circup install -r requirements.txt\n Installed 'adafruit_bmp280'.\n Installed 'adafruit_lis3mdl'.\n Installed 'adafruit_lsm6ds'.\n Installed 'adafruit_sht31d'.\n Installed 'neopixel'.\n\nUninstall a module or modules like this::\n\n $ circup uninstall adafruit_thermal_printer\n Uninstalled 'adafruit_thermal_printer'.\n\n $ circup uninstall adafruit_thermal_printer adafruit_bus_io\n Uninstalled 'adafruit_thermal_printer'.\n Uninstalled 'adafruit_bus_io'.\n\nUse the ``--verbose`` flag to see the logs as the command is working::\n\n $ circup --verbose freeze\n Logging to /home/ntoll/.cache/circup/log/circup.log\n\n 10/18/2020 00:54:43 INFO: ### Started Circup ###\n 10/18/2020 00:54:43 INFO: Found device: /Volumes/CIRCUITPY\n Found device at /Volumes/CIRCUITPY, running CircuitPython 6.0.0-alpha.1-1352-gf0b37313c.\n 10/18/2020 00:54:44 INFO: Freeze\n 10/18/2020 00:54:44 INFO: Found device: /Volumes/CIRCUITPY\n ... etc ...\n\nThe ``--path`` flag let's you pass in a different path to the CircuitPython\nmounted volume. This is helpful when you have renamed or have more than one\nCircuitPython devices attached::\n\n $ circup --path /run/media/user/CIRCUITPY1 list\n\nThe ``--version`` flag will tell you the current version of the\n``circup`` command itself::\n\n $ circup --version\n CircUp, A CircuitPython module updater. Version 0.0.1\n\n\nTo use circup via the `Web Workflow <https://learn.adafruit.com/getting-started-with-web-workflow-using-the-code-editor>`_. on devices that support it. Use the ``--host`` and ``--password`` arguments before your circup command.::\n\n $ circup --host 192.168.1.119 --password s3cr3t install adafruit_hid\n $ circup --host cpy-9573b2.local --password s3cr3t install adafruit_hid\n\nThat's it!\n\n\nLibrary Name Autocomplete\n-------------------------\n\nWhen enabled, circup will autocomplete library names, simliar to other command line tools.\n\nFor example:\n\n ``circup install n`` + tab -``circup install neopixel`` (+tab: offers ``neopixel`` and ``neopixel_spi`` completions)\n\n ``circup install a`` + tab -``circup install adafruit\\_`` + m a g + tab -``circup install adafruit_magtag``\n\nHow to Activate Library Name Autocomplete\n-----------------------------------------\n\nIn order to activate shell completion, you need to inform your shell that completion is available for your script. Any Click application automatically provides support for that.\n\nFor Bash, add this to ~/.bashrc::\n\n eval \"$(_CIRCUP_COMPLETE=bash_source circup)\"\n\nFor Zsh, add this to ~/.zshrc::\n\n eval \"$(_CIRCUP_COMPLETE=zsh_source circup)\"\n\nFor Fish, add this to ~/.config/fish/completions/foo-bar.fish::\n\n eval (env _CIRCUP_COMPLETE=fish_source circup)\n\nOpen a new shell to enable completion. Or run the eval command directly in your current shell to enable it temporarily.\n### Activation Script\n\nThe above eval examples will invoke your application every time a shell is started. This may slow down shell startup time significantly.\n\nAlternatively, export the generated completion code as a static script to be executed. You can ship this file with your builds; tools like Git do this. At least Zsh will also cache the results of completion files, but not eval scripts.\n\nFor Bash::\n\n _CIRCUP_COMPLETE=bash_source circup circup-complete.sh\n\nFor Zsh::\n\n _CIRCUP_COMPLETE=zsh_source circup circup-complete.sh\n\nFor Fish::\n\n _CIRCUP_COMPLETE=fish_source circup circup-complete.sh\n\nIn .bashrc or .zshrc, source the script instead of the eval command::\n\n . /path/to/circup-complete.sh\n\nFor Fish, add the file to the completions directory::\n\n _CIRCUP_COMPLETE=fish_source circup ~/.config/fish/completions/circup-complete.fish\n\n\n.. note::\n\n If you find a bug, or you want to suggest an enhancement or new feature\n feel free to create an issue or submit a pull request here:\n\n https://github.com/adafruit/circup\n\n\nDiscussion of this tool happens on the Adafruit CircuitPython\n`Discord channel <https://discord.gg/rqrKDjU>`_.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A tool to manage/update libraries on CircuitPython devices.",
"version": "1.8.0",
"project_urls": {
"Homepage": "https://github.com/adafruit/circup"
},
"split_keywords": [
"adafruit",
" blinka",
" circuitpython",
" micropython",
" libraries"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7cce8ff82df705b2a6ea5cbbdabb95b55e7411acdea4a9edf2db873b5cfc4950",
"md5": "ee99f85320405f9b8b9aa84fa17aaa14",
"sha256": "38ab0cb121dd68dbd1c819f486c51fd1abdc00f272b88d5508b75aa7d742bf92"
},
"downloads": -1,
"filename": "circup-1.8.0.tar.gz",
"has_sig": false,
"md5_digest": "ee99f85320405f9b8b9aa84fa17aaa14",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 110402,
"upload_time": "2024-04-24T20:54:55",
"upload_time_iso_8601": "2024-04-24T20:54:55.515087Z",
"url": "https://files.pythonhosted.org/packages/7c/ce/8ff82df705b2a6ea5cbbdabb95b55e7411acdea4a9edf2db873b5cfc4950/circup-1.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-24 20:54:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adafruit",
"github_project": "circup",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "appdirs",
"specs": []
},
{
"name": "Click",
"specs": []
},
{
"name": "findimports",
"specs": []
},
{
"name": "requests",
"specs": []
},
{
"name": "semver",
"specs": []
},
{
"name": "toml",
"specs": []
},
{
"name": "update_checker",
"specs": []
}
],
"lcname": "circup"
}
JSON
