From f0232c99c516a1c8074a8e3511d5f87fb13029fb Mon Sep 17 00:00:00 2001 From: Scott Shawcroft Date: Thu, 8 Feb 2018 12:48:59 -0800 Subject: [PATCH] Changes based on feedback in #600. --- docs/design_guide.rst | 59 +++++++++++++++++++++++++++++++------------ 1 file changed, 43 insertions(+), 16 deletions(-) diff --git a/docs/design_guide.rst b/docs/design_guide.rst index 6abb12684b..fcd27911dd 100644 --- a/docs/design_guide.rst +++ b/docs/design_guide.rst @@ -1,13 +1,20 @@ Design Guide ============ -This guide covers a variety of development practices for CircuitPython core and library APIs. Consistency with these practices ensures that beginners can learn a pattern once and apply it throughout the CircuitPython ecosystem. +This guide covers a variety of development practices for CircuitPython core and library APIs. These +APIs are both `built-into CircuitPython +`_ and those that are +`distributed on GitHub `_ +and in the `Adafruit `_ and `Community +`_ bundles. Consistency with these +practices ensures that beginners can learn a pattern once and apply it throughout the CircuitPython +ecosystem. Start libraries with the cookiecutter ------------------------------------- -Cookiecutter is a cool tool that lets you bootstrap a new repo based on another -repo. We've made one `here `_ +Cookiecutter is a tool that lets you bootstrap a new repo based on another repo. +We've made one `here `_ for CircuitPython libraries that include configs for Travis CI and ReadTheDocs along with a setup.py, license, code of conduct and readme. @@ -18,6 +25,10 @@ along with a setup.py, license, code of conduct and readme. cookiecutter gh:adafruit/cookiecutter-adafruit-circuitpython +Cookiecutter will provide a series of prompts relating to the library and then create a new +directory with all of the files. See `the CircuitPython cookiecutter README +`_ for more details. + Module Naming ------------- @@ -26,7 +37,11 @@ Adafruit funded libraries should be under the ``Adafruit_CircuitPython_`` and have a corresponding ``adafruit_`` directory (aka package) or ``adafruit_.py`` file (aka module). -Community created libraries should have the format ``CircuitPython_`` and +If the name would normally have a space, such as "Thermal Printer", use an underscore instead +("Thermal_Printer"). This underscore will be used everywhere even when the separation between +"adafruit" and "circuitpython" is done with a ``-``. Use the underscore in the cookiecutter prompts. + +Community created libraries should have the repo format ``CircuitPython_`` and not have the ``adafruit_`` module or package prefix. Both should have the CircuitPython repository topic on GitHub. @@ -88,7 +103,7 @@ Verify your device -------------------------------------------------------------------------------- Whenever possible, make sure device you are talking to is the device you expect. -If not, raise a ValueError. Beware that I2C addresses can be identical on +If not, raise a RuntimeError. Beware that I2C addresses can be identical on different devices so read registers you know to make sure they match your expectation. Validating this upfront will help catch mistakes. @@ -123,6 +138,18 @@ modules to add extra functionality. By distinguishing API boundaries at modules you increase the likelihood that incorrect expectations are found on import and not randomly during runtime. +When adding a new module for additional functionality related to a CPython +module do NOT simply prefix it with u. This is not a large enough differentiation +from CPython. This is the MicroPython convention and they use u* modules +interchangeably with the CPython name. This is confusing. Instead, think up a +new name that is related to the extra functionality you are adding. + +For example, storage mounting and unmounting related functions were moved from +``uos`` into a new `storage` module. Terminal related functions were moved into +`multiterminal`. These names better match their functionality and do not +conflict with CPython names. Make sure to check that you don't conflict with +CPython libraries too. That way we can port the API to CPython in the future. + Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -196,7 +223,7 @@ goes. Regardless of how the attribute is implemented, it should have a short description of what state it represents including the type, possible values and/or units. It should be marked as ``(read-only)`` or ``(write-only)`` at the end of -the first line for attributes that are not both readable and writeable. +the first line for attributes that are not both readable and writable. Instance attributes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -248,7 +275,7 @@ Read-only example:: @property def temperature(self): """ - The current temperature in degrees Celcius. (read-only) + The current temperature in degrees Celsius. (read-only) The device may require calibration to get accurate readings. """ @@ -260,7 +287,7 @@ Renders as: .. py:attribute:: temperature :noindex: - The current temperature in degrees Celcius. (read-only) + The current temperature in degrees Celsius. (read-only) The device may require calibration to get accurate readings. @@ -464,14 +491,14 @@ properties. +-----------------------+-----------------------+-------------------------------------------------------------------------+ | ``datetime`` | time.struct | date and time | +-----------------------+-----------------------+-------------------------------------------------------------------------+ - -Common APIs --------------------------------------------------------------------------------- - -Outside of sensors, having common methods amongst drivers for similar devices -such as devices can be really useful. Its early days however. For now, try to -adhere to guidelines in this document. Once a design is settled on, add it as a -subsection to this one. +| ``duty_cycle`` | int | 16-bit PWM duty cycle (regardless of output resolution) | ++-----------------------+-----------------------+-------------------------------------------------------------------------+ +| ``frequency`` | int | Hertz | ++-----------------------+-----------------------+-------------------------------------------------------------------------+ +| ``value`` | bool | Digital logic | ++-----------------------+-----------------------+-------------------------------------------------------------------------+ +| ``value`` | int | 16-bit Analog value, unit-less | ++-----------------------+-----------------------+-------------------------------------------------------------------------+ Adding native modules --------------------------------------------------------------------------------