_bootstrap.md

   1 * Python Library - library/name/__init__.py
   2 * At least *one*  test - library/tests/test_setup.py
   3 * Examples
   4
   5 # In Detail
   6
   7 To get started, copy the contents of this repository (excluding the .git directory) and run `_bootstrap.sh` to highlight substitutions you need to make.
   8
   9 Be careful to copy *all* files, including those starting with a . such as `.travis.yml`.
  10
  11 A Makefile is provided to automate some tests, checks and package building. You should use it!
  12
  13 ## Library
  14
  15 ### Structure
  16
  17 Libraries should be singleton if they pertain to a HAT or pHAT and class-based if they are for breakouts with selectable addresses.
  18
  19 A singleton library would work like this:
  20
  21 ```
  22 import library
  23
  24 library.do_something()
  25 ```
  26
  27 Whereas a class-based library requires an instance of its class:
  28
  29 ```
  30 import library
  31
  32 device = library.Library()
  33
  34 device.do_something()
  35 ```
  36
  37 ### Linting
  38
  39 You should ensure you either run `flake8` while writing the library, or use an IDE/Editor with linting.
  40
  41 All libraries (and example code) should stick to PEP8 style guides, although you can ignore long line warnings (E501) if you feel they're unwarranted.
  42
  43 ### Testing
  44
  45 At least one test script should be used to prevent obvious errors and omissions from creeping into the library.
  46
  47 You should use `tox` to run the test scripts:
  48
  49 ```
  50 sudo pip install tox
  51 cd library/
  52 tox
  53 ```
  54
  55 ## Examples
  56
  57 Examples should use hyphens and short, descriptive names, ie: `rainbow-larson.py`
  58
  59 Examples should include a `print()` front-matter introducing them, ie:
  60
  61 ```
  62 print("""rainbow-larson.py - Display a larson scanning rainbow
  63
  64 Press Ctrl+C to exit.
  65
  66 """)
  67 ```
  68
  69 # Deployment
  70
  71 Before deploying you should `make python-testdeploy` and verify that the package looks good and is installable from test PyPi.
  72
  73 You should also `make check` to catch common errors, including mismatched version numbers, trailing whitespace and DOS line-endings.
  74
  75 Subsequent to deployment you should `git tag -a "vX.X.X" -m "Version X.X.X"` and `git push origin master --follow-tags` to tag a release on GitHub that matches the deployed code.