Documentation with examples.
This commit is contained in:
Nicholas H.Tollervey
parent
c5e467e670
commit
8ac9a61a77
2 changed files with 121 additions and 21 deletions
132
README.rst
132
README.rst
|
|
@ -1,35 +1,135 @@
|
|||
CircUp
|
||||
======
|
||||
|
||||
A tool to manage and update libraries on a CircuitPython device.
|
||||
A tool to manage and update libraries (modules) on a CircuitPython device.
|
||||
|
||||
How
|
||||
---
|
||||
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?
|
||||
-----
|
||||
|
||||
Each CircuitPython library on the device (``.py``, *NOT* ``.mpy`` at this time)
|
||||
has a version number and a github repo URL.
|
||||
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 recet (compared to what is in the referenced GitHub repository). If
|
||||
the libraries are out of date, the utility downloads them to the local device
|
||||
and/or local system in a zip file.
|
||||
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.
|
||||
|
||||
Example libraries:
|
||||
The Adafruit CircuitPython Bundle can be found here:
|
||||
|
||||
https://github.com/adafruit/Adafruit_CircuitPython_Bundle/releases/download/20190830/adafruit-circuitpython-bundle-py-20190830.zip
|
||||
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
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
Example usage::
|
||||
First, plug in a device running CircuiPython. This should appear as a mounted
|
||||
storage device called ``CIRCUITPYTHON``.
|
||||
|
||||
circup list
|
||||
To get help, just type the command::
|
||||
|
||||
Module Version Latest
|
||||
----------- ------- ------
|
||||
foo 1.0.1 1.1.0
|
||||
bar 19.3 19.4
|
||||
baz 0.3.1 0.9
|
||||
$ 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.
|
||||
|
||||
Commands:
|
||||
freeze Output details of all the modules found on the connected...
|
||||
list Lists all out of date modules found on the connected
|
||||
CIRCUITPYTHON...
|
||||
update Checks for out-of-date modules on the connected CIRCUITPYTHON...
|
||||
|
||||
To show version information for all the modules currently on a connected
|
||||
CIRCUITPYTHON device::
|
||||
|
||||
$ circup freeze
|
||||
Logging to /home/ntoll/.cache/circup/log/circup.log
|
||||
|
||||
adafruit_binascii==v1.0
|
||||
adafruit_bme280==2.3.1
|
||||
adafruit_ble==1.0.2
|
||||
|
||||
To list all the modules that require an update::
|
||||
|
||||
$ circup list
|
||||
Logging to /home/ntoll/.cache/circup/log/circup.log
|
||||
|
||||
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
|
||||
Logging to /home/ntoll/.cache/circup/log/circup.log
|
||||
|
||||
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
|
||||
|
||||
Use the ``--verbose`` flag to see the logs as the command is working::
|
||||
|
||||
$ circup --verbose freeze
|
||||
|
||||
|
||||
|
||||
Started 2019-09-05 13:13:41.031822
|
||||
INFO: Freeze
|
||||
INFO: Found device: /media/ntoll/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!
|
||||
|
||||
.. note::
|
||||
|
||||
If you find a bug, or you want to suggest an enhancement or new feature
|
||||
feel free to submit a bug report or pull request here:
|
||||
|
||||
https://github.com/adafruit/circup
|
||||
|
||||
Developer Setup
|
||||
---------------
|
||||
|
|
|
|||
10
circup.py
10
circup.py
|
|
@ -148,7 +148,7 @@ class Module:
|
|||
name, local version and remote version.
|
||||
|
||||
:return: A tuple containing the module's name, version on the connected
|
||||
device and version in the latest bundle.
|
||||
device and version in the latest bundle.
|
||||
"""
|
||||
loc = self.device_version if self.device_version else "unknown"
|
||||
rem = self.bundle_version if self.bundle_version else "unknown"
|
||||
|
|
@ -309,7 +309,7 @@ def find_modules():
|
|||
device.
|
||||
|
||||
:return: A list of Module instances describing the current state of the
|
||||
modules on the connected device.
|
||||
modules on the connected device.
|
||||
"""
|
||||
try:
|
||||
device_modules = get_device_versions()
|
||||
|
|
@ -343,7 +343,7 @@ def get_bundle_versions():
|
|||
of the library bundle.
|
||||
|
||||
:return: A dictionary of metadata about the modules available in the
|
||||
library bundle.
|
||||
library bundle.
|
||||
"""
|
||||
ensure_latest_bundle()
|
||||
for path, subdirs, files in os.walk(BUNDLE_DIR):
|
||||
|
|
@ -357,7 +357,7 @@ def get_device_versions():
|
|||
Returns a dictionary of metadata from modules on the connected device.
|
||||
|
||||
:return: A dictionary of metadata about the modules available on the
|
||||
connected device.
|
||||
connected device.
|
||||
"""
|
||||
device_path = find_device()
|
||||
if device_path is None:
|
||||
|
|
@ -428,7 +428,7 @@ def get_bundle(tag):
|
|||
|
||||
:param str tag: The GIT tag to use to download the bundle.
|
||||
:return: The location of the resulting zip file in a temporary location on
|
||||
the local filesystem.
|
||||
the local filesystem.
|
||||
"""
|
||||
url = (
|
||||
"https://github.com/adafruit/Adafruit_CircuitPython_Bundle"
|
||||
|
|
|
|||
Loading…
Reference in a new issue