djsundog/circuitpython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #863 from dhalbert/3.0_doc_updates

Browse Source 
RTD documentation updates
This commit is contained in:
Scott Shawcroft 2018-05-23 12:57:34 -07:00 committed by GitHub
commit 8e6feecf11
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 84 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
README.rst
View File

@ -103,10 +103,15 @@ Differences from `MicroPython <https://github.com/micropython/micropython>`__
CircuitPython:
- includes a port for Atmel SAMD21 (Commonly known as M0 in Adafruit
product names.)
- supports only Atmel SAMD21 and ESP8266 ports.
- includes a ports for MicroChip SAMD21 (Commonly known as M0 in Adafruit
product names and SAMD51 (M4).
- supports only SAMD21, SAMD51, and ESP8266 ports. An nRF port is under
development.
- tracks MicroPython's releases (not master).
- Longints (arbitrary-length integers) are enabled for most M0
Express boards (those boards with SPI flash chips external
to the microcontroller), and for all M4 builds.
Longints are disabled on other boards due to lack of flash space.
Behavior
~~~~~~~~

4
docs/design_guide.rst
View File

@ -441,10 +441,10 @@ buffers.
Examples
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ustruct.pack
struct.pack
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use `ustruct.pack_into` instead of `ustruct.pack`.
Use `struct.pack_into` instead of `struct.pack`.
Sensor properties and units
--------------------------------------------------------------------------------

2
docs/library/array.rst
View File

@ -1,8 +1,6 @@
:mod:`array` -- arrays of numeric data
======================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: array
:synopsis: efficient arrays of numeric data

18
docs/library/builtins.rst
View File

@ -1,18 +1,14 @@
Builtin functions and exceptions
================================
.. warning::
These builtins are inherited from MicroPython and may not work in CircuitPython
as documented or at all! If work differently from CPython, then their behavior
may change.
All builtin functions and exceptions are described here. They are also
available via ``builtins`` module.
Functions and types
-------------------
Not all of these functions and types are turned on in all CircuitPython ports, for space reasons.
.. function:: abs()
.. function:: all()
@ -62,6 +58,8 @@ Functions and types
.. class:: frozenset()
`frozenset()` is not enabled on non-Express CircuitPython boards.
.. function:: getattr()
.. function:: globals()
@ -80,12 +78,12 @@ Functions and types
.. classmethod:: from_bytes(bytes, byteorder)
In MicroPython, `byteorder` parameter must be positional (this is
In CircuitPython, `byteorder` parameter must be positional (this is
compatible with CPython).
.. method:: to_bytes(size, byteorder)
In MicroPython, `byteorder` parameter must be positional (this is
In CircuitPython, `byteorder` parameter must be positional (this is
compatible with CPython).
.. function:: isinstance()
@ -130,6 +128,8 @@ Functions and types
.. function:: reversed()
`reversed()` is not enabled on non-Express CircuitPython boards.
.. function:: round()
.. class:: set()
@ -182,7 +182,7 @@ Exceptions
.. exception:: OSError
|see_cpython| `OSError`. MicroPython doesn't implement ``errno``
|see_cpython| `OSError`. CircuitPython doesn't implement the ``errno``
attribute, instead use the standard way to access exception arguments:
``exc.args[0]``.

6
docs/library/gc.rst
View File

@ -31,7 +31,7 @@ Functions
.. admonition:: Difference to CPython
:class: attention
This function is MicroPython extension.
This function is a MicroPython extension.
.. function:: mem_free()
@ -41,7 +41,7 @@ Functions
.. admonition:: Difference to CPython
:class: attention
This function is MicroPython extension.
This function is a MicroPython extension.
.. function:: threshold([amount])
@ -63,6 +63,6 @@ Functions
.. admonition:: Difference to CPython
:class: attention
This function is a MicroPython extension. CPython has a similar
This function is a a MicroPython extension. CPython has a similar
function - ``set_threshold()``, but due to different GC
implementations, its signature and semantics are different.

61
docs/library/index.rst
View File

@ -3,43 +3,74 @@
MicroPython libraries
=====================
.. warning::
These modules are inherited from MicroPython and may not work in CircuitPython
as documented or at all! If they do work, they may change at any time.
Python standard libraries and micro-libraries
---------------------------------------------
These libraries are inherited from MicroPython.
They are similar to the standard Python libraries with the same name
or with the "u" prefix dropped.
They implement a subset of or a variant of the corresponding
standard Python library.
.. warning::
Though these MicroPython-based libraries are available in CircuitPython,
their functionality may change in the future, perhaps significantly.
As CircuitPython continues to develop, new versions of these libraries will
be created that are more compliant with the standard Python libraries.
You may need to change your code later if you rely
on any non-standard functionality they currently provide.
CircuitPython's goal long-term goalis that code written in CircuitPython
using Python standard libraries will be runnable on CPython without changes.
Some libraries below are not enabled on CircuitPython builds with
limited flash memory, usually on non-Express builds:
``uerrno``, ``ure``.
Some libraries are not currently enabled in any CircuitPython build, but may be in the future:
``uio``, ``ujson``, ``uzlib``.
Some libraries are only enabled only WiFi-capable ports (ESP8266, nRF)
because they are typically used for network software:
``binascii``, ``hashlib``, ``uheapq``, ``uselect``, ``ussl``.
Not all of these are enabled on all WiFi-capable ports.
.. toctree::
:maxdepth: 1
builtins.rst
uheapq.rst
array.rst
gc.rst
sys.rst
binascii.rst
collections.rst
uerrno.rst
gc.rst
hashlib.rst
uheapq.rst
sys.rst
uerrno.rst
uio.rst
ujson.rst
ure.rst
uselect.rst
usocket.rst
ussl.rst
ustruct.rst
uzlib.rst
Omitted functions in the ``string`` library
-------------------------------------------
MicroPython-specific libraries
------------------------------
A few string operations are not enabled on CircuitPython
M0 non-Express builds, due to limited flash memory:
``string.center()``, ``string.partition()``, ``string.splitlines()``,
``string.reversed()``.
Functionality specific to the MicroPython implementation is available in
the following libraries.
CircuitPython/MicroPython-specific libraries
--------------------------------------------
Functionality specific to the CircuitPython/MicroPython implementation is available in
the following libraries. These libraries may change signficantly or be removed in future
versions of CircuitPtyon.
.. toctree::
:maxdepth: 1

20
docs/library/sys.rst
View File

@ -45,12 +45,12 @@ Constants
.. data:: implementation
Object with information about the current Python implementation. For
MicroPython, it has following attributes:
CircuitPython, it has following attributes:
* *name* - string "micropython"
* *name* - string "circuitpython"
* *version* - tuple (major, minor, micro), e.g. (1, 7, 0)
This object is the recommended way to distinguish MicroPython from other
This object is the recommended way to distinguish CircuitPython from other
Python implementations (note that it still may not exist in the very
minimal ports).
@ -58,13 +58,13 @@ Constants
:class: attention
CPython mandates more attributes for this object, but the actual useful
bare minimum is implemented in MicroPython.
bare minimum is implemented in CircuitPython.
.. data:: maxsize
Maximum value which a native integer type can hold on the current platform,
or maximum value representable by MicroPython integer type, if it's smaller
than platform max value (that is the case for MicroPython ports without
or maximum value representable by CircuitPython integer type, if it's smaller
than platform max value (that is the case for CircuitPython ports without
long int support).
This attribute is useful for detecting "bitness" of a platform (32-bit vs
@ -96,11 +96,11 @@ Constants
.. data:: platform
The platform that MicroPython is running on. For OS/RTOS ports, this is
The platform that CircuitPython is running on. For OS/RTOS ports, this is
usually an identifier of the OS, e.g. ``"linux"``. For baremetal ports it
is an identifier of a board, e.g. ``"pyboard"`` for the original MicroPython
reference board. It thus can be used to distinguish one board from another.
If you need to check whether your program runs on MicroPython (vs other
is an identifier of the chip on a board, e.g. ``"MicroChip SAMD51"``.
It thus can be used to distinguish one board from another.
If you need to check whether your program runs on CircuitPython (vs other
Python implementation), use `sys.implementation` instead.
.. data:: stderr

44
docs/library/ustruct.rst
View File

@ -1,44 +0,0 @@
:mod:`ustruct` -- pack and unpack primitive data types
======================================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: ustruct
:synopsis: pack and unpack primitive data types
|see_cpython_module| :mod:`cpython:struct`.
Supported size/byte order prefixes: ``@``, ``<``, ``>``, ``!``.
Supported format codes: ``b``, ``B``, ``h``, ``H``, ``i``, ``I``, ``l``,
``L``, ``q``, ``Q``, ``s``, ``P``, ``f``, ``d`` (the latter 2 depending
on the floating-point support).
Functions
---------
.. function:: calcsize(fmt)
Return the number of bytes needed to store the given *fmt*.
.. function:: pack(fmt, v1, v2, ...)
Pack the values *v1*, *v2*, ... according to the format string *fmt*.
The return value is a bytes object encoding the values.
.. function:: pack_into(fmt, buffer, offset, v1, v2, ...)
Pack the values *v1*, *v2*, ... according to the format string *fmt*
into a *buffer* starting at *offset*. *offset* may be negative to count
from the end of *buffer*.
.. function:: unpack(fmt, data)
Unpack from the *data* according to the format string *fmt*.
The return value is a tuple of the unpacked values.
.. function:: unpack_from(fmt, data, offset=0)
Unpack from the *data* starting at *offset* according to the format string
*fmt*. *offset* may be negative to count from the end of *buffer*. The return
value is a tuple of the unpacked values.

9
docs/templates/unsupported_in_circuitpython.inc vendored
View File

@ -1,5 +1,8 @@
.. warning::
This module is inherited from MicroPython and may not work in CircuitPython
as documented or at all! If they do work, they may change at any time. It is
unsupported.
Though this MicroPython-based library is available for use in CircuitPython,
its functionality may change in the future, perhaps significantly.
As CircuitPython continues to develop, it may be changed
to comply more closely with the corresponding standard Python library.
You may need to change your code later if you rely
on any non-standard functionality it currently provides.