A tool to manage/update libraries on CircuitPython devices.
Project description
A tool to manage and update libraries (modules) on a CircuitPython device.
Installation
Circup requires Python 3.5 or higher.
In a virtualenv, 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.
What?
Each CircuitPython library on the device (.py, NOT .mpy at this time) 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). 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:
Usage
First, plug in a device running CircuiPython. This should appear as a mounted storage device called CIRCUITPYTHON.
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.
--version Show the version and exit.
--help Show this message and exit.
-r --requirement Supports requirements.txt tracking of library
requirements with freeze and install commands.
Commands:
freeze Output details of all the modules found on the connected...
install Install a named module 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.
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 $ 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 onto the connected device with:
$ circup install 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 like this:
$ circup uninstall adafruit_thermal_printer Uninstalled 'adafruit_thermal_printer'.
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 ...
Finally, 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
That’s it!
Developer Setup
Clone the repository then make a virtualenv. From the root of the project, install the requirements:
pip install -e ".[dev]"
Run the test suite:
make check
There is a Makefile that helps with most of the common workflows associated with development. Typing “make” on its own will list the options thus:
$ make There is no default Makefile target right now. Try: make clean - reset the project and remove auto-generated assets. make pyflakes - run the PyFlakes code checker. make pycodestyle - run the PEP8 style checker. make test - run the test suite. make coverage - view a report on test coverage. make tidy - tidy code with the 'black' formatter. make check - run all the checkers and tests. make dist - make a dist/wheel for the project. make publish-test - publish the project to PyPI test instance. make publish-live - publish the project to PyPI production. make docs - run sphinx to create project documentation.
How?
The circup tool checks for a connected CircuitPython device by interrogating the local filesystem to find a path to a directory which ends with "CIRCUITPYTHON" (the name under which a CircuitPython device is mounted by the host operating system). This is handled in the find_device function.
A Python module on a connected device is represented by an instance of the Module class. This class provides useful methods for discerning if the module is out of date, returning useful representations of it in order to display information to the user, or updating the module on the connected device with whatever the version is in the latest Adafruit CircuitPython Bundle.
All of the libraries included in the Adafruit CircuitPython Bundle contain, somewhere within their code, two metadata objects called __version__ and __repo__.
The __repo__ object is a string containing the GitHub repository URL, as used to clone the project.
The __version__ object is interesting because within the source code in Git the value is always the string "0.0.0-auto.0". When a new release is made of the bundle, this value is automatically replaced by the build scripts to the correct version information, which will always conform to the semver standard.
Given this context, the circup tool will check a configuration file to discern what it thinks is the latest version of the bundle. If there is no configuration file (for example, on first run), then the bundle version is assumed to be "0".
Next, it checks GitHub for the tag value (denoting the version) of the very latest bundle release. Bundle versions are based upon the date of release, for instance "20190904". If the latest version on GitHub is later than the version circup currently has, then the latest version of the bundle is automatically downloaded and cached away somewhere.
In this way, the circup tool is able to have available to it both a path to a connected CIRCUITPYTHON devce and a copy of the latest version, including the all important version information, of the Adafruit CircuitPython Bundle.
Exactly the same function (get_modules) is used to extract the metadata from the modules on both the connected device and in the bundle cache. This metadata is used to instantiate instances of the Module class which is subsequently used to facilitate the various commands the tool makes available.
These commands are defined at the very end of the circup.py code.
Unit tests can be found in the tests directory. CircUp uses pytest style testing conventions. Test functions should include a comment to describe its intention. We currently have 100% unit test coverage for all the core functionality (excluding functions used to define the CLI commands).
To run the full test suite, type:
make check
All code is formatted using the stylistic conventions enforced by black. The tidying of code formatting is part of the make check process, but you can also just use:
make tidy
Please see the output from make for more information about the various available options to help you work with the code base. TL;DR make check runs everything.
Before submitting a PR, please remember to make check. ;-)
CircUp uses the Click module to run command-line interaction. The AppDirs module is used to determine where to store user-specific assets created by the tool in such a way that meets the host operating system’s usual conventions. The python-semver package is used to validate and compare the semver values associated with modules. The ubiquitous requests module is used for HTTP activity.
Documentation, generated by Sphinx, is based on this README and assembled by assets in the doc subdirectory. The latest version of the docs will be found on Read the Docs.
Discussion of this tool happens on the Adafruit CircuitPython Discord channel.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
File details
Details for the file circup-0.4.0.tar.gz.
File metadata
- Download URL: circup-0.4.0.tar.gz
- Upload date:
- Size: 81.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.2.0 pkginfo/1.6.1 requests/2.25.1 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.54.1 CPython/3.9.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | d60b152526145f608d7891227fd453e323c70be1031b808fa131b57df6feedcf |
|
| MD5 | 65e1cda992cb198ac418030a5d3f502b |
|
| BLAKE2b-256 | 057582dba0426c28b6d067de2d548ebc9cd624f3feae3640f4944f3de6fc9e32 |
