Closed
Description
We want to use CircuitPython libraries on other platforms such as CPython on Raspberry Pi and MicroPython. To do so, we need to better document the dependencies and get builds auto-released to pypi where pip gets them from.
Requirements
To do this work you'll need the adafruit-travis pypi username and password. You will also need adafruit-adabots GitHub password. Please contact @tannewt or @kattni if you are interested.
You must have Ruby and travis installed. Instructions can be found on the Travis CI repo. On Mac OS, once you have Ruby updated, if you run into issues, you can brew install travis (see comment below for details).
Instructions
Upgrading a repo requires a number of steps:
- Use
travis(the Ruby CLI) to encrypt the pypi password into the travis.yml. The blob changes every repo. You MUST be logged into the Travis CLI using theadafruit-adabotGitHub credentials. Runtravis encrypt --com --add deploy.passwordand follow the prompt. It will reformat the.travis.ymland drop the header comment. That's ok and can be left as is. The result will be that .travis.yml has something like this:
password:
secure: oqlm4dJIzX2JH8Qbd+qU0g+M+1NSHD0f9pWQxvdhl+JlCtzRmBtyv6t24EN+SUGD3eKOK9A21/+QxsQJ2sB8/g8qh07OUNKw+erv9NqA2Wc0oHvOpwpN+TkS6hF0GI/Tn53hwm+qiTsXmBfbDoXDyu6Qe9rsht7Llv1wbHErCk7vkZ9zEL0zfhkgV5hzXPoRdwQclLeyleoJMyw0ZdfPqupMCGGAMPd6aTIYQfJ1PVmzYu9VqtK7yEB9lltc6U16dwp2huN2HBz5EzlRWszCli8mx1+MuZxNFlYkMo8vgWpSQmJpw22nSzI8ez57QibNGEm9u4Y9nb7PlzH9ZOeTVI7OZ9k3BPSN0db8WKGLz9VJxyTilqPNs737TCf36tdshPnuEtEDwk8YNReyK5uE5TnjnnXL2g3qSyhIniKLusY5d9cF3PEhwG6DcNqt39NrT6rG9PaeURYzKY19BgwhWD2CucEM6RDBRp+31citzM35NjET+5+xSOmDXdCdr+Ar+AWNxyfGn0N+Za/de8JyFjuk5TN4muB61eJPXPpinn8+egNyeiONPT96vJDVvFrEdG3bIEspYd6ZAMQ8Aou1Ii+CxOEXiY+57AK20LAieX8Nv2sTLLHo5wa7c4xghHVZdN187cesqm0LZtNYGhs/CeMP+9bC3bn7/IHGdcRZvg4=- Now modify the deploy section to add a pypi section and including the password portion in it. You may need to add the
-beforeprovider: releasesand addoverwrite: trueas well.
deploy:
- provider: releases
api_key: "$GITHUB_TOKEN"
file_glob: true
file: "$TRAVIS_BUILD_DIR/bundles/*"
skip_cleanup: true
overwrite: true
on:
tags: true
- provider: pypi
user: adafruit-travis
on:
tags: true
password:
secure: oqlm4dJIzX2JH8Qbd+qU0g+M+1NSHD0f9pWQxvdhl+JlCtzRmBtyv6t24EN+SUGD3eKOK9A21/+QxsQJ2sB8/g8qh07OUNKw+erv9NqA2Wc0oHvOpwpN+TkS6hF0GI/Tn53hwm+qiTsXmBfbDoXDyu6Qe9rsht7Llv1wbHErCk7vkZ9zEL0zfhkgV5hzXPoRdwQclLeyleoJMyw0ZdfPqupMCGGAMPd6aTIYQfJ1PVmzYu9VqtK7yEB9lltc6U16dwp2huN2HBz5EzlRWszCli8mx1+MuZxNFlYkMo8vgWpSQmJpw22nSzI8ez57QibNGEm9u4Y9nb7PlzH9ZOeTVI7OZ9k3BPSN0db8WKGLz9VJxyTilqPNs737TCf36tdshPnuEtEDwk8YNReyK5uE5TnjnnXL2g3qSyhIniKLusY5d9cF3PEhwG6DcNqt39NrT6rG9PaeURYzKY19BgwhWD2CucEM6RDBRp+31citzM35NjET+5+xSOmDXdCdr+Ar+AWNxyfGn0N+Za/de8JyFjuk5TN4muB61eJPXPpinn8+egNyeiONPT96vJDVvFrEdG3bIEspYd6ZAMQ8Aou1Ii+CxOEXiY+57AK20LAieX8Nv2sTLLHo5wa7c4xghHVZdN187cesqm0LZtNYGhs/CeMP+9bC3bn7/IHGdcRZvg4=- The pypi release step runs commands in the console after the serial section so we need to ensure we leave it in the top level. So, change the docs line by adding
&& cd ..to the end. The end result is:
- cd docs && sphinx-build -E -W -b html . _build/html && cd ..- Add an install command for installing the requirements.txt
- pip install -r requirements.txtinto.travis.yml. Full section:
install:
- pip install -r requirements.txt
- pip install circuitpython-build-tools Sphinx sphinx-rtd-theme
- pip install --force-reinstall pylint==1.9.2note circuitpython-travis-build-tools was renamed circuitpython-build-tools
- Next we need to add/update a
setup.pyfile to the repo. Change the name to match the GitHub repo except lowercase and-instead of_. Update the description, url and packages list. If the library is a single py file replacepackageswithpy_modules. They both take a list without the .py extension. Here is a full example:
"""A setuptools based setup module.
See:
https://packaging.python.org/en/latest/distributing.html
https://github.com/pypa/sampleproject
"""
# Always prefer setuptools over distutils
from setuptools import setup, find_packages
# To use a consistent encoding
from codecs import open
from os import path
here = path.abspath(path.dirname(__file__))
# Get the long description from the README file
with open(path.join(here, 'README.rst'), encoding='utf-8') as f:
long_description = f.read()
setup(
name='adafruit-circuitpython-seesaw',
use_scm_version=True,
setup_requires=['setuptools_scm'],
description='CircuitPython library for controlling a SeeSaw helper chip.',
long_description=long_description,
long_description_content_type='text/x-rst',
# The project's main homepage.
url='https://github.com/adafruit/Adafruit_CircuitPython_seesaw',
# Author details
author='Adafruit Industries',
author_email='circuitpython@adafruit.com',
install_requires=['Adafruit-Blinka', 'adafruit-circuitpython-busdevice'],
# Choose your license
license='MIT',
# See https://pypi.python.org/pypi?%3Aaction=list_classifiers
classifiers=[
'Development Status :: 3 - Alpha',
'Intended Audience :: Developers',
'Topic :: Software Development :: Libraries',
'Topic :: System :: Hardware',
'License :: OSI Approved :: MIT License',
'Programming Language :: Python :: 3',
'Programming Language :: Python :: 3.4',
'Programming Language :: Python :: 3.5',
],
# What does your project relate to?
keywords='adafruit seesaw hardware micropython circuitpython',
# You can just specify the packages manually here if your project is
# simple. Or you can use find_packages().
packages=['adafruit_seesaw'],
)if its a single-python-file type driver, use something like: py_modules=['adafruit_mcp230xx'],
- Update dependencies! Dependencies are documented in two places:
- in setup.py under
install_requires - in the
requirements.txtfile. Check the source files for imports from other libraries and add them in both places. If CircuitPython APIs are used such asdigitalio,busioorfrom micropython import constthen addAdafruit-Blinkaas a dependency. - rename
adafruit-circuitpython-bus-devicetoadafruit-circuitpython-busdevicein requirements.txt - Remove any autodoc_mock_imports from
docs/conf.pybecause sphinx and Travis will install therequirements.txtbefore running sphinx.
- in setup.py under
- Test the setup.py locally with
python3 setup.py sdist. - Commit or PR the changes.
- Once the change is in the GitHub repo watch Travis and make sure the build remains green.
- Create a new release to trigger the actual pypi deploy. Increment the patch position (the right-most number.) All libraries should have release notes of the form:
<release notes>
To use in CircuitPython, download the .mpy file and copy it to the `lib` folder on the `CIRCUITPY` drive. Or, simply install the [Adafruit CircuitPython bundle](https://github.com/adafruit/Adafruit_CircuitPython_Bundle).
To use in CPython, `pip install adafruit-circuitpython-<libname>`.
Read the [docs](http://circuitpython.readthedocs.io/projects/<libname>/en/latest/) for info on how to use it.
- If the deploy fails (check through Travis), you'll need to edit a file, commit it and verify Travis then release. Edit the release created in 10 to give it a new tag and release number. Editing will move the release notes so the previous one is simply a tag.
- You are done! Thank you so much.
TODO
- Update AdaBot to list libraries not available on pypi.