diff --git a/README.rst-stubs b/README.rst-stubs index 7b8919db1f..00880563cb 100644 --- a/README.rst-stubs +++ b/README.rst-stubs @@ -11,223 +11,11 @@ CircuitPython `Project Structure <#project-structure>`__ **CircuitPython** is a *beginner friendly*, open source version of Python for tiny, inexpensive -computers called microcontrollers. Microcontrollers are the brains of many electronics including a -wide variety of development boards used to build hobby projects and prototypes. CircuitPython in -electronics is one of the best ways to learn to code because it connects code to reality. Simply -install CircuitPython on a supported board via drag and drop and then edit a ``code.py`` file on -the CIRCUITPY drive. The code will automatically reload. No software installs are needed besides a -text editor (we recommend `Mu `_ for beginners.) +computers called microcontrollers. -CircuitPython features unified Python core APIs and a growing list of 150+ device libraries and -drivers that work with it. These libraries also work on single board computers with regular -Python via the `Adafruit Blinka Library `_. - -CircuitPython is based on `MicroPython `_. See -`below <#differences-from-micropython>`_ for differences. CircuitPython development is sponsored by -`Adafruit `_ and is available on their educational development boards. Please -support both MicroPython and Adafruit. - -Get CircuitPython ------------------- - -Official binaries for all supported boards are available through -`circuitpython.org/downloads `_. The site includes stable, unstable and -continuous builds. Full release notes and assets are available through -`GitHub releases `_ as well. - -Documentation -------------- - -Guides and videos are available through the `Adafruit Learning -System `__ under the `CircuitPython -category `__. An API -reference is also available on `Read the Docs -`__. A collection of awesome -resources can be found at `Awesome CircuitPython `__. - -Specifically useful documentation when starting out: - -- `Welcome to CircuitPython `__ -- `CircuitPython Essentials `__ -- `Example Code `__ - -Code Search ------------- -GitHub doesn't currently support code search on forks. Therefore, CircuitPython doesn't have code search through GitHub because it is a fork of MicroPython. Luckily, `SourceGraph `_ has free code search for public repos like CircuitPython. So, visit `sourcegraph.com/github.com/adafruit/circuitpython `_ to search the CircuitPython codebase online. - -Contributing ------------- - -See -`CONTRIBUTING.md `__ -for full guidelines but please be aware that by contributing to this -project you are agreeing to the `Code of -Conduct `__. -Contributors who follow the `Code of -Conduct `__ -are welcome to submit pull requests and they will be promptly reviewed -by project admins. Please join the -`Discord `__ too. - -Branding ------------- - -While we are happy to see CircuitPython forked and modified, we'd appreciate it if forked releases -not use the name "CircuitPython" or the Blinka logo. "CircuitPython" means something special to -us and those who learn about it. As a result, we'd like to make sure products referring to it meet a -common set of requirements. - -If you'd like to use the term "CircuitPython" and Blinka for your product here is what we ask: - -* Your product is supported by the primary - `"adafruit/circuitpython" `_ repo. This way we can - update any custom code as we update the CircuitPython internals. -* Your product is listed on `circuitpython.org `__ (source - `here `_). This is to ensure that a user of your - product can always download the latest version of CircuitPython from the standard place. -* Your product has a user accessible USB plug which appears as a CIRCUITPY drive when plugged in. - -If you choose not to meet these requirements, then we ask you call your version of CircuitPython -something else (for example, SuperDuperPython) and not use the Blinka logo. You can say it is -"CircuitPython-compatible" if most CircuitPython drivers will work with it. - --------------- - -Differences from `MicroPython `__ ------------------------------------------------------------------------------ - -CircuitPython: - -- Supports native USB on all boards, allowing file editing without special tools. -- Floats (aka decimals) are enabled for all builds. -- Error messages are translated into 10+ languages. -- Does not support concurrency within Python (including interrupts and threading). Some concurrency - is achieved with native modules for tasks that require it such as audio file playback. - -Behavior -~~~~~~~~ - -- The order that files are run and the state that is shared between - them. CircuitPython's goal is to clarify the role of each file and - make each file independent from each other. -- ``boot.py`` (or ``settings.py``) runs only once on start up before - USB is initialized. This lays the ground work for configuring USB at - startup rather than it being fixed. Since serial is not available, - output is written to ``boot_out.txt``. -- ``code.py`` (or ``main.py``) is run after every reload until it - finishes or is interrupted. After it is done running, the vm and - hardware is reinitialized. **This means you cannot read state from** - ``code.py`` **in the REPL anymore, as the REPL is a fresh vm.** CircuitPython's goal for this - change includes reducing confusion about pins and memory being used. -- After the main code is finished the REPL can be entered by pressing any key. -- Autoreload state will be maintained across reload. -- Adds a safe mode that does not run user code after a hard crash or - brown out. The hope is that this will make it easier to fix code that - causes nasty crashes by making it available through mass storage - after the crash. A reset (the button) is needed after it's fixed to - get back into normal mode. -- RGB status LED indicating CircuitPython state, and errors through a sequence of colored flashes. -- Re-runs ``code.py`` or other main file after file system writes over USB mass storage. (Disable with - ``supervisor.disable_autoreload()``) -- Autoreload is disabled while the REPL is active. -- Main is one of these: ``code.txt``, ``code.py``, ``main.py``, - ``main.txt`` -- Boot is one of these: ``settings.txt``, ``settings.py``, ``boot.py``, - ``boot.txt`` - -API -~~~ - -- Unified hardware APIs. Documented on - `ReadTheDocs `_. -- API docs are rST within the C files in ``shared-bindings``. -- No ``machine`` API. - -Modules -~~~~~~~ - -- No module aliasing. (``uos`` and ``utime`` are not available as - ``os`` and ``time`` respectively.) Instead ``os``, ``time``, and - ``random`` are CPython compatible. -- New ``storage`` module which manages file system mounts. - (Functionality from ``uos`` in MicroPython.) -- Modules with a CPython counterpart, such as ``time``, ``os`` and - ``random``, are strict - `subsets `__ - of their `CPython - version `__. - Therefore, code from CircuitPython is runnable on CPython but not - necessarily the reverse. -- tick count is available as - `time.monotonic() `__ - --------------- - -Project Structure ------------------ - -Here is an overview of the top-level source code directories. - -Core -~~~~ - -The core code of -`MicroPython `__ is shared -amongst ports including CircuitPython: - -- ``docs`` High level user documentation in Sphinx reStructuredText - format. -- ``drivers`` External device drivers written in Python. -- ``examples`` A few example Python scripts. -- ``extmod`` Shared C code used in multiple ports' modules. -- ``lib`` Shared core C code including externally developed libraries - such as FATFS. -- ``logo`` The CircuitPython logo. -- ``mpy-cross`` A cross compiler that converts Python files to byte - code prior to being run in MicroPython. Useful for reducing library - size. -- ``py`` Core Python implementation, including compiler, runtime, and - core library. -- ``shared-bindings`` Shared definition of Python modules, their docs - and backing C APIs. Ports must implement the C API to support the - corresponding module. -- ``shared-module`` Shared implementation of Python modules that may be - based on ``common-hal``. -- ``tests`` Test framework and test scripts. -- ``tools`` Various tools, including the pyboard.py module. - -Ports -~~~~~ - -Ports include the code unique to a microcontroller line. - -================ ============================================================ -Supported Support status -================ ============================================================ -atmel-samd ``SAMD21`` stable | ``SAMD51`` stable -cxd56 stable -esp32s2 stable -litex alpha -mimxrt10xx alpha -nrf stable -raspberrypi stable -stm ``F4`` stable | ``others`` beta -unix alpha -================ ============================================================ - -- ``stable`` Highly unlikely to have bugs or missing functionality. -- ``beta`` Being actively improved but may be missing functionality and have bugs. -- ``alpha`` Will have bugs and missing functionality. - -Boards -~~~~~~ - -- Each ``port`` has a ``boards`` directory containing variations of boards - which belong to a specific microcontroller line. -- A list of native modules supported by a particular board can be found - `here `__. - -`Back to Top <#circuitpython>`__ +This package contains the "stubs", or type definitions for CircuitPython. With some advanced +editors and other tools, this information can be identify TypeErrors, AttributeErrors, and other +problems before you deploy your code to a device and can even help autocomplete your code. .. |Build Status| image:: https://github.com/adafruit/circuitpython/workflows/Build%20CI/badge.svg :target: https://github.com/adafruit/circuitpython/actions?query=branch%3Amain