Initial commit.

Based on the V2 docs as of f3908e2c295ec9e4ad9da47541021af1c948b827 and
upstream MicroPython docs for the few modules we don't have micro:bit
docs for.

Updated after merge of bbcmicrobit/micropython#725

Some notes on discrepancies in discrepancies.md. I'll make more tweaks
as I get feedback on issues raised.

`builtins` contain too many symbols for MicroPython. I'll fix that by
comparing with the introspection results in a subsequent commit.

Author: microbit-matt-hillsdon

.github/workflows/node.js.yml

@@ -0,0 +1,31 @@
+# This workflow will do a clean install of node dependencies, cache/restore them, build the source code and run tests across different versions of node
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
+
+name: Node.js CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [16.x]
+        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v2
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm ci
+    - run: npm run build --if-present
+    - run: npm test

.gitignore

@@ -0,0 +1,3 @@
+/typeshed.json
+/node_modules/
+*.rst

.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+  "python.formatting.provider": "black",
+  "python.analysis.typeshedPaths": [
+    "/Users/mth/Development/microbit-foundation/micropython-microbit-stubs/typeshed/"
+  ],
+  "python.analysis.typeCheckingMode": "basic"
+}

README.md

@@ -0,0 +1,13 @@
+# micro:bit MicroPython stubs for editor support
+
+## Credit and licensing
+
+builtins and utility definitions are derived from [typeshed](https://github.com/python/typeshed). Further work is required to review these to ensure that we don't have stubs for definitions MicroPython does not support. These stubs don't provide documentation.
+
+MicroPython and micro:bit stubs are based on the restructured text documentation for [micro:bit](https://github.com/bbcmicrobit/micropython/tree/v2-docs) and, where not otherwise covered in micro:bit-specific docs, [MicroPython](https://github.com/micropython/micropython/tree/master/docs/library). These stubs provide documentation.
+
+Typeshed is Apache 2.0 licensed.
+
+MicroPython is MIT Licensed and Copyright (c) 2013-2021 Damien P. George.
+MicroPython for the micro:bit is MIT licensed and Copyright (c) 2013-2016 The MicroPython-on-micro:bit Developers (see https://github.com/bbcmicrobit/micropython/blob/v2-docs/AUTHORS).
+

browser-package.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+"""
+Outputs a JSON file containing all the stubs and a Pyright config file.
+
+This is intended for web apps that need the stubs client side.
+"""
+import os
+import json
+
+results = dict(files={})
+for (source, prefix) in (("typeshed", "/typeshed/"), ("config", "/src/")):
+    for (dirpath, dirnames, filenames) in os.walk(source):
+        for f in sorted(filenames):
+            path = os.path.join(dirpath, f)
+            destination = os.path.join(
+                prefix, os.path.join(*path.split(os.path.sep)[1:])
+            )
+            print(f"{path} -> {destination}")
+            text = open(path, "r").read()
+            results["files"][destination] = text
+
+with open("typeshed.json", "w") as f:
+    f.write(json.dumps(results, indent=2))

config/pyrightconfig.json

@@ -0,0 +1,9 @@
+{ 
+  "pythonVersion": "3.6",
+  "pythonPlatform": "Linux",
+  "typeCheckingMode": "basic",
+  "typeshedPath": "/typeshed/",
+  "reportMissingModuleSource": false,
+  "reportWildcardImportFromLibrary": false,
+  "verboseOutput": true
+ }

discrepancies.md

@@ -0,0 +1,116 @@
+# Notes
+
+These are working notes on discrepancies found when creating these stubs.
+
+## Cross-cutting issues
+
+Module docs throughout are a bit arbitrary and need review.
+
+Various docs don't line up exactly because @overload is the best way to represent their typings so requires docs to be customised for each scenario.
+
+## Module-specific issues
+
+### gc
+
+isenabled is undocumented in MicroPython docs (not added).
+
+### audio
+
+[AudioFrame.copyfrom](https://github.com/microbit-foundation/micropython-microbit-v2/blob/bca4dc5690998e8e5de07019a44185fc9b9ea080/src/codal_port/modaudio.c#L301) is undocumented (not added).
+
+AudioFrame implements some operations that aren't clearly documented (e.g. you can add them, multiple by an integer). I added stubs for these as they're used in examples.
+
+### uart
+
+uart.readinto is misindented in the docs (minor).
+there's a method documented as having been removed so I've omitted it from the stubs
+
+### microbit
+
+- image - type of buffer in second __init__ option
+- text modified to split across __init__ definitions
+- "Same as" language is unhelpful.
+- __sub__ and __div__ added based on examples but not in docs.
+- microphone - the doc style here is a bit different to elsewhere, might be less good in Pyright?
+
+### micropython
+
+- schedule is undocumented (I've not added it)
+- micropython.schedule is missing from our docs. Why? It is on the device (checked on V2).
+
+### neopixel
+
+Has long but important module docstring with important warnings for the user.
+I've removed the images and reproduced it otherwise in full.
+
+Some complication with write/show. Fine for stubs but will need revisiting for docs.
+
+ws2812_write is undocumented (here and in microbit module)
+ORDER is undocumented
+
+### pins (in microbit)
+
+get_analog_period_microseconds isn't documented
+
+pin_logo isn't really a pin... it just has:
+		CAPACITIVE
+		RESISTIVE
+		is_touched
+		set_touch_mode
+how to model this? currently incorrectly a touch pin.
+
+pins need class docs
+
+NO_PULL etc. aren't available on MicroBitDigitalPin. You need to use the instances
+to access. Can/should we model this?
+
+### machine
+
+	mem16
+	mem32
+	mem8
+are undocumented
+
+### os
+
+ilistdir and stat are undocumented (not added)
+
+### radio
+
+In the docs and stubs but not on a V2 (V1 not checked):
+
+```
+>>> radio.RATE_250KBIT
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+AttributeError: 'module' object has no attribute 'RATE_250KBIT'
+```
+
+It's commented out in the source: https://github.com/microbit-foundation/micropython-microbit-v2/blame/eba8995843ebc7246765b364710543c9ffee344a/src/codal_port/modradio.c#L269
+
+I've added a note to the docstring for now.
+
+### microphone
+
+```python
+>>> from microbit import *
+>>> repr(microphone.current_event())
+'None'
+>>> repr(microphone.current_event())
+"SoundEvent('loud')"
+```
+
+but [docs](https://microbit-micropython.readthedocs.io/en/v2-docs/microphone.html#microbit.microphone.current_event) (and for now stubs) claim it cannot return None
+
+Raised https://github.com/microbit-foundation/micropython-microbit-v2/issues/86
+
+## Interesting code failures
+
+In waveforms.py
+
+```python
+frames = [ None ] * 32
+```
+
+...is a problematic initialization pattern for arrays. Can we relax the rules?
+Is the pattern widespread? What options does Pyright have to relax behaviour around None?

examples/micropython/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2013-2016 The MicroPython-on-micro:bit Developers, as listed
+in the accompanying AUTHORS file
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

examples/micropython/analog_watch.py

@@ -0,0 +1,35 @@
+from microbit import *
+
+hands = Image.ALL_CLOCKS
+
+#A centre dot of brightness 2.
+ticker_image = Image("2\n").crop(-2,-2,5,5)
+
+#Adjust these to taste
+MINUTE_BRIGHT = 0.1111
+HOUR_BRIGHT = 0.55555
+
+#Generate hands for 5 minute intervals
+def fiveticks():
+    fivemins = 0
+    hours = 0
+    while True:
+        yield  hands[fivemins]*MINUTE_BRIGHT + hands[hours]*HOUR_BRIGHT
+        fivemins = (fivemins+1)%12
+        hours = (hours + (fivemins == 0))%12
+
+#Generate hands with ticker superimposed for 1 minute intervals.      
+def ticks():
+    on = True
+    for face in fiveticks():
+        for i in range(5):
+            if on:
+                yield face + ticker_image
+            else:
+                yield face - ticker_image
+            on = not on
+
+#Run a clock speeded up 60 times, so we can watch the animation.
+for tick in ticks():
+    display.show(tick)
+    sleep(1000)

examples/micropython/asmleds.py.todo

@@ -0,0 +1,57 @@
+"""
+This script uses the inline assembler to make the LEDs light up
+in a pattern based on how they are multiplexed in rows/cols.
+"""
+
+# row pins: 13, 14, 15
+# col pins: 4..12 inclusive
+# GPIO words starting at 0x50000500:
+#   RESERVED, OUT, OUTSET, OUTCLR, IN, DIR, DIRSET, DIRCLR
+
+@micropython.asm_thumb
+def led_cycle():
+    b(START)
+
+    # DELAY routine
+    label(DELAY)
+    mov(r3, 0xa0)
+    lsl(r3, r3, 11)
+    label(delay_loop)
+    sub(r3, 1)
+    bne(delay_loop)
+    bx(lr)
+
+    label(START)
+
+    cpsid('i')          # disable interrupts so we control the display
+
+    mov(r0, 0x50)       # r0=0x50
+    lsl(r0, r0, 16)     # r0=0x500000
+    add(r0, 0x05)       # r0=0x500005
+    lsl(r0, r0, 8)      # r0=0x50000500 -- this points to GPIO registers
+    mov(r1, 0b111)
+    lsl(r1, r1, 13)     # r1=0xe000
+    str(r1, [r0, 8])    # pull all rows high
+
+    mov(r1, 1 << 4)     # r1 holds current col bit
+    mov(r2, 9)          # r2 holds number of cols left
+    label(loop_on)
+    str(r1, [r0, 12])   # pull col low to turn LEDs on
+    bl(DELAY)           # wait
+    lsl(r1, r1, 1)      # shift to next col
+    sub(r2, 1)          # decrease col counter
+    bne(loop_on)        # loop while there are still cols left
+
+    mov(r1, 1 << 4)     # r1 holds current col bit
+    mov(r2, 9)          # r2 holds number of cols left
+    label(loop_off)
+    str(r1, [r0, 8])    # pull col high to turn LEDs off
+    bl(DELAY)           # wait
+    lsl(r1, r1, 1)      # shift to next col
+    sub(r2, 1)          # decrease col counter
+    bne(loop_off)       # loop while there are still cols left
+
+    cpsie('i')      # enable interrupts
+
+for i in range(4):
+    led_cycle()