all: Bump version to 1.20.0.

Signed-off-by: Damien George <damien@micropython.org>

.git-blame-ignore-revs

@@ -1,3 +1,18 @@
+# top: Update Python formatting to black "2023 stable style".
+8b2748269244304854b3462cb8902952b4dcb892
+
+# all: Reformat remaining C code that doesn't have a space after a comma.
+5b700b0af90591d6b1a2c087bb8de6b7f1bfdd2d
+
+# ports: Reformat more C and Python source code.
+5c32111fa0e31e451b0f1666bdf926be2fdfd82c
+
+# all: Update Python formatting to latest Black version 22.1.0.
+ab2923dfa1174dc177f0a90cb00a7e4ff87958d2
+
+# all: Update Python formatting to latest Black version 21.12b0.
+3770fab33449a5dadf8eb06edfae0767e75320a6
+
 # tools/gen-cpydiff.py: Fix formatting of doc strings for new Black.
 0f78c36c5aa458a954eed39a46942209107a553e
 

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,25 @@
+---
+name: Bug report
+about: Report an issue
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+* Please search existing issues before raising a new issue. For questions about MicroPython or for help using MicroPython, or any sort of "how do I?" requests, please use the Discussions tab or raise a documentation request instead.
+
+* In your issue, please include a clear and concise description of what the bug is, the expected output, and how to replicate it.
+
+* If this issue involves external hardware, please include links to relevant datasheets and schematics.
+
+* If you are seeing code being executed incorrectly, please provide a minimal example and expected output (e.g. comparison to CPython).
+
+* For build issues, please include full details of your environment, compiler versions, command lines, and build output.
+
+* Please provide as much information as possible about the version of MicroPython you're running, such as:
+ - firmware file name
+ - git commit hash and port/board
+ - version information shown in the REPL (hit Ctrl-B to see the startup message)
+
+* Remove all placeholder text above before submitting.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: MicroPython GitHub Discussions
+    url: https://github.com/orgs/micropython/discussions
+    about: Community discussion about all things MicroPython. This is the best place to start if you have questions about using MicroPython or getting started with MicroPython development.
+  - name: MicroPython Documentation
+    url: https://docs.micropython.org/
+    about: Documentation for using and working with MicroPython and libraries.
+  - name: MicroPython Downloads
+    url: https://micropython.org/download/
+    about: Pre-built firmware and information for most supported boards.

.github/ISSUE_TEMPLATE/documentation.md

@@ -0,0 +1,16 @@
+---
+name: Documentation issue
+about: Report areas of the documentation or examples that need improvement
+title: 'docs: '
+labels: documentation
+assignees: ''
+
+---
+
+* Please search existing issues before raising a new issue. For questions about MicroPython or for help using MicroPython, or any sort of "how do I?" requests, please use the Discussions tab instead.
+
+* Describe what was missing from the documentation and/or what was incorrect/incomplete.
+
+* If possible, please link to the relevant page on https://docs.micropython.org/
+
+* Remove all placeholder text above before submitting.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,24 @@
+---
+name: Feature request
+about: Request a feature or improvement
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+* Please search existing issues before raising a new issue. For questions about MicroPython or for help using MicroPython, or any sort of "how do I?" requests, please use the Discussions tab or raise a documentation request instead.
+
+* Describe the feature you'd like to see added to MicroPython. In particular, what does this feature enable and why is it useful. MicroPython aims to strike a balance between functionality and code size, so please consider whether this feature can be optionally enabled and whether it can be provided in other ways (e.g. pure-Python library).
+
+* For core Python features, where possible please include a link to the relevant PEP.
+
+* For new architectures / ports / boards, please provide links to relevant documentation, specifications, and toolchains. Any information about the popularity and unique features about this hardware would also be useful.
+
+* For features for existing ports (e.g. new peripherals or microcontroller features), please describe which port(s) it applies too, and whether this is could be an extension to the machine API or a port-specific module?
+
+* For drivers (e.g. for external hardware), please link to datasheets and/or existing drivers from other sources.
+
+* Who do you expect will implement the feature you are requesting? Would you be willing to sponsor this work?
+
+* Remove all placeholder text above before submitting.

.github/ISSUE_TEMPLATE/security.md

@@ -0,0 +1,16 @@
+---
+name: Security report
+about: Report a security issue or vunerability in MicroPython
+title: ''
+labels: security
+assignees: ''
+
+---
+
+* If you need to raise this issue privately with the MicroPython team, please email contact@micropython.org instead.
+
+* Include a clear and concise description of what the security issue is.
+
+* What does this issue allow an attacker to do?
+
+* Remove all placeholder text above before submitting.

.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+updates:
+  # Maintain dependencies for GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"

.github/workflows/code_formatting.yml

@@ -2,12 +2,16 @@ name: Check code formatting
 
 on: [push, pull_request]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
-    - uses: actions/checkout@v2
-    - uses: actions/setup-python@v1
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v4
     - name: Install packages
       run: source tools/ci.sh && ci_code_formatting_setup
     - name: Run code formatting

.github/workflows/code_size.yml

@@ -12,11 +12,15 @@ on:
       - 'ports/bare-arm/**'
       - 'ports/minimal/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
       with:
         fetch-depth: 100
     - name: Install packages
@@ -24,4 +28,18 @@ jobs:
     - name: Build
       run: source tools/ci.sh && ci_code_size_build
     - name: Compute code size difference
-      run: tools/metrics.py diff --error-threshold 0 ~/size0 ~/size1
+      run: tools/metrics.py diff ~/size0 ~/size1 | tee diff
+    - name: Save PR number
+      if: github.event_name == 'pull_request'
+      env:
+        PR_NUMBER: ${{ github.event.number }}
+      run: echo $PR_NUMBER > pr_number
+    - name: Upload diff
+      if: github.event_name == 'pull_request'
+      uses: actions/upload-artifact@v3
+      with:
+        name: code-size-report
+        path: |
+          diff
+          pr_number
+        retention-days: 1

.github/workflows/code_size_comment.yml

@@ -0,0 +1,105 @@
+name: Code size comment
+
+on:
+  workflow_run:
+    workflows: [Check code size]
+    types: [completed]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  comment:
+    runs-on: ubuntu-20.04
+    steps:
+      - name: 'Download artifact'
+        id: download-artifact
+        uses: actions/github-script@v6
+        with:
+          result-encoding: string
+          script: |
+            const fs = require('fs');
+
+            const allArtifacts = await github.rest.actions.listWorkflowRunArtifacts({
+               owner: context.repo.owner,
+               repo: context.repo.repo,
+               run_id: context.payload.workflow_run.id,
+            });
+
+            const matchArtifact = allArtifacts.data.artifacts.filter((artifact) => {
+              return artifact.name == "code-size-report"
+            });
+
+            if (matchArtifact.length === 0) {
+              console.log('no matching artifact found');
+              console.log('result: "skip"');
+
+              return 'skip';
+            }
+
+            const download = await github.rest.actions.downloadArtifact({
+               owner: context.repo.owner,
+               repo: context.repo.repo,
+               artifact_id: matchArtifact[0].id,
+               archive_format: 'zip',
+            });
+
+            fs.writeFileSync(`${process.env.GITHUB_WORKSPACE}/code-size-report.zip`, Buffer.from(download.data));
+
+            console.log('artifact downloaded to `code-size-report.zip`');
+            console.log('result: "ok"');
+
+            return 'ok';
+      - name: 'Unzip artifact'
+        if: steps.download-artifact.outputs.result == 'ok'
+        run: unzip code-size-report.zip
+      - name: Post comment to pull request
+        if: steps.download-artifact.outputs.result == 'ok'
+        uses: actions/github-script@v6
+        with:
+          github-token: ${{secrets.GITHUB_TOKEN}}
+          script: |
+            const fs = require('fs');
+
+            const prNumber = Number(fs.readFileSync('pr_number'));
+            const codeSizeReport = `Code size report:
+
+            \`\`\`
+            ${fs.readFileSync('diff')}
+            \`\`\`
+            `;
+
+            const comments = await github.paginate(
+              github.rest.issues.listComments,
+              {
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: prNumber,
+              }
+            );
+
+            comments.reverse();
+
+            const previousComment = comments.find(comment =>
+              comment.user.login === 'github-actions[bot]'
+            )
+
+            // if github-actions[bot] already made a comment, update it,
+            // otherwise create a new comment.
+
+            if (previousComment) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: previousComment.id,
+                body: codeSizeReport,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: prNumber,
+                body: codeSizeReport,
+              });
+            }

.github/workflows/commit_formatting.yml

@@ -2,13 +2,17 @@ name: Check commit message formatting
 
 on: [push, pull_request]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
       with:
         fetch-depth: '100'
-    - uses: actions/setup-python@v1
+    - uses: actions/setup-python@v4
     - name: Check commit message formatting
       run: source tools/ci.sh && ci_commit_formatting_run

.github/workflows/docs.yml

@@ -5,13 +5,17 @@ on:
     paths:
       - docs/**
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
-    - uses: actions/setup-python@v1
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v4
     - name: Install Python packages
       run: pip install Sphinx
     - name: Build docs

.github/workflows/examples.yml

@@ -0,0 +1,25 @@
+name: Check examples
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'examples/**'
+      - 'ports/unix/**'
+      - 'py/**'
+      - 'shared/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  embedding:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Build
+      run: make -C examples/embedding -f micropython_embed.mk && make -C examples/embedding
+    - name: Run
+      run: ./examples/embedding/embed | grep "hello world"

.github/workflows/mpremote.yml

@@ -0,0 +1,31 @@
+name: Package mpremote
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'tools/**'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        # Version is determined from git,
+        # should be deep enough to get to latest tag
+        fetch-depth: '1000'
+    - run: |
+        git fetch --prune --unshallow --tags
+    - uses: actions/setup-python@v4
+    - name: Install build tools
+      run: pip install build
+    - name: Build mpremote wheel
+      run: cd tools/mpremote && python -m build --wheel
+    - name: Archive mpremote wheel
+      uses: actions/upload-artifact@v3
+      with:
+        name: mpremote
+        path: |
+          tools/mpremote/dist/mpremote*.whl

.github/workflows/mpy_format.yml

@@ -0,0 +1,24 @@
+name: .mpy file format and tools
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'examples/**'
+      - 'tests/**'
+      - 'tools/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-20.04 # use 20.04 to get python2
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_mpy_format_setup
+    - name: Test mpy-tool.py
+      run: source tools/ci.sh && ci_mpy_format_test

.github/workflows/ports.yml

@@ -8,11 +8,15 @@ on:
       - 'tools/**'
       - ports/**
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Build ports download metadata
       run: mkdir boards && ./tools/autobuild/build-downloads.py . ./boards

.github/workflows/ports_cc3200.yml

@@ -8,15 +8,20 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'drivers/**'
       - 'ports/cc3200/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_cc3200_setup
     - name: Build

.github/workflows/ports_esp32.yml

@@ -8,15 +8,20 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'drivers/**'
       - 'ports/esp32/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build_idf402:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_esp32_idf402_setup
     - name: Build
@@ -25,7 +30,7 @@ jobs:
   build_idf44:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_esp32_idf44_setup
     - name: Build

.github/workflows/ports_esp8266.yml

@@ -8,15 +8,20 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'drivers/**'
       - 'ports/esp8266/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_esp8266_setup && ci_esp8266_path >> $GITHUB_PATH
     - name: Build

.github/workflows/ports_javascript.yml

@@ -1,24 +0,0 @@
-name: javascript port
-
-on:
-  push:
-  pull_request:
-    paths:
-      - '.github/workflows/*.yml'
-      - 'tools/**'
-      - 'py/**'
-      - 'extmod/**'
-      - 'lib/**'
-      - 'ports/javascript/**'
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v2
-    - name: Install packages
-      run: source tools/ci.sh && ci_javascript_setup
-    - name: Build
-      run: source tools/ci.sh && ci_javascript_build
-    - name: Run tests
-      run: source tools/ci.sh && ci_javascript_run_tests

.github/workflows/ports_mimxrt.yml

@@ -8,15 +8,20 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'drivers/**'
       - 'ports/mimxrt/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_mimxrt_setup
     - name: Build

.github/workflows/ports_nrf.yml

@@ -8,15 +8,20 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'drivers/**'
       - 'ports/nrf/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_nrf_setup
     - name: Build

.github/workflows/ports_powerpc.yml

@@ -8,15 +8,20 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'drivers/**'
       - 'ports/powerpc/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_powerpc_setup
     - name: Build

.github/workflows/ports_qemu-arm.yml

@@ -8,20 +8,25 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'drivers/**'
       - 'ports/qemu-arm/**'
       - 'tests/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build_and_test:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_qemu_arm_setup
     - name: Build and run test suite
       run: source tools/ci.sh && ci_qemu_arm_build
     - name: Print failures
       if: failure()
-      run: grep --text "FAIL" ports/qemu-arm/build/console.out
+      run: grep --before-context=100 --text "FAIL" ports/qemu-arm/build/console.out

.github/workflows/ports_renesas-ra.yml

@@ -0,0 +1,29 @@
+name: renesas-ra port
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'tools/**'
+      - 'py/**'
+      - 'extmod/**'
+      - 'shared/**'
+      - 'lib/**'
+      - 'drivers/**'
+      - 'ports/renesas-ra/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build_renesas_ra_board:
+    runs-on: ubuntu-20.04
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_renesas_ra_setup
+    - name: Build
+      run: source tools/ci.sh && ci_renesas_ra_board_build
+

.github/workflows/ports_rp2.yml

@@ -8,15 +8,20 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'drivers/**'
       - 'ports/rp2/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_rp2_setup
     - name: Build

.github/workflows/ports_samd.yml

@@ -8,15 +8,20 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'drivers/**'
       - 'ports/samd/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_samd_setup
     - name: Build

.github/workflows/ports_stm32.yml

@@ -8,15 +8,20 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'drivers/**'
       - 'ports/stm32/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build_pyb:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_stm32_setup
     - name: Build
@@ -25,7 +30,7 @@ jobs:
   build_nucleo:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_stm32_setup
     - name: Build

.github/workflows/ports_teensy.yml

@@ -8,15 +8,20 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'drivers/**'
       - 'ports/teensy/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_teensy_setup
     - name: Build

.github/workflows/ports_unix.yml

@@ -8,16 +8,22 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'examples/**'
+      - 'mpy-cross/**'
       - 'ports/unix/**'
       - 'tests/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   minimal:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Build
       run: source tools/ci.sh && ci_unix_minimal_build
     - name: Run main test suite
@@ -29,36 +35,22 @@ jobs:
   reproducible:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Build with reproducible date
       run: source tools/ci.sh && ci_unix_minimal_build
       env:
         SOURCE_DATE_EPOCH: 1234567890
     - name: Check reproducible build date
-      run: echo | ports/unix/micropython-minimal -i | grep 'on 2009-02-13;'
+      run: echo | ports/unix/build-minimal/micropython -i | grep 'on 2009-02-13;'
 
   standard:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Build
       run: source tools/ci.sh && ci_unix_standard_build
     - name: Run main test suite
       run: source tools/ci.sh && ci_unix_standard_run_tests
-    - name: Run performance benchmarks
-      run: source tools/ci.sh && ci_unix_standard_run_perfbench
-    - name: Print failures
-      if: failure()
-      run: tests/run-tests.py --print-failures
-
-  dev:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v2
-    - name: Build
-      run: source tools/ci.sh && ci_unix_dev_build
-    - name: Run main test suite
-      run: source tools/ci.sh && ci_unix_dev_run_tests
     - name: Print failures
       if: failure()
       run: tests/run-tests.py --print-failures
@@ -66,13 +58,15 @@ jobs:
   coverage:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_unix_coverage_setup
     - name: Build
       run: source tools/ci.sh && ci_unix_coverage_build
     - name: Run main test suite
       run: source tools/ci.sh && ci_unix_coverage_run_tests
+    - name: Test merging .mpy files
+      run: source tools/ci.sh && ci_unix_coverage_run_mpy_merge_tests
     - name: Build native mpy modules
       run: source tools/ci.sh && ci_native_mpy_modules_build
     - name: Test importing .mpy generated by mpy_ld.py
@@ -82,7 +76,7 @@ jobs:
         (cd ports/unix && gcov -o build-coverage/py ../../py/*.c || true)
         (cd ports/unix && gcov -o build-coverage/extmod ../../extmod/*.c || true)
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v1
+      uses: codecov/codecov-action@v3
       with:
         fail_ci_if_error: true
         verbose: true
@@ -93,7 +87,7 @@ jobs:
   coverage_32bit:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_unix_32bit_setup
     - name: Build
@@ -109,9 +103,9 @@ jobs:
       run: tests/run-tests.py --print-failures
 
   nanbox:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-20.04 # use 20.04 to get python2
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_unix_32bit_setup
     - name: Build
@@ -125,7 +119,7 @@ jobs:
   float:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Build
       run: source tools/ci.sh && ci_unix_float_build
     - name: Run main test suite
@@ -137,7 +131,7 @@ jobs:
   stackless_clang:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_unix_clang_setup
     - name: Build
@@ -151,7 +145,7 @@ jobs:
   float_clang:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_unix_clang_setup
     - name: Build
@@ -165,7 +159,7 @@ jobs:
   settrace:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Build
       run: source tools/ci.sh && ci_unix_settrace_build
     - name: Run main test suite
@@ -177,7 +171,7 @@ jobs:
   settrace_stackless:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Build
       run: source tools/ci.sh && ci_unix_settrace_stackless_build
     - name: Run main test suite
@@ -189,8 +183,8 @@ jobs:
   macos:
     runs-on: macos-11.0
     steps:
-    - uses: actions/checkout@v2
-    - uses: actions/setup-python@v2
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v4
       with:
         python-version: '3.8'
     - name: Build
@@ -204,7 +198,7 @@ jobs:
   qemu_mips:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_unix_qemu_mips_setup
     - name: Build
@@ -218,7 +212,7 @@ jobs:
   qemu_arm:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_unix_qemu_arm_setup
     - name: Build

.github/workflows/ports_webassembly.yml

@@ -0,0 +1,32 @@
+name: webassembly port
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'tools/**'
+      - 'py/**'
+      - 'extmod/**'
+      - 'shared/**'
+      - 'lib/**'
+      - 'ports/webassembly/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_webassembly_setup
+    - name: Build
+      run: source tools/ci.sh && ci_webassembly_build
+    - name: Run tests
+      run: source tools/ci.sh && ci_webassembly_run_tests
+    - name: Print failures
+      if: failure()
+      run: tests/run-tests.py --print-failures

.github/workflows/ports_windows.yml

@@ -8,15 +8,20 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'ports/unix/**'
       - 'ports/windows/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_windows_setup
     - name: Build

.github/workflows/ports_zephyr.yml

@@ -8,14 +8,19 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'ports/zephyr/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_zephyr_setup
     - name: Install Zephyr

.gitignore

@@ -1,48 +1,25 @@
-# Compiled Sources
-###################
-*.o
-*.a
-*.elf
-*.bin
-*.map
-*.hex
-*.dis
-*.exe
-
-# Packages
-############
-
-# Logs and Databases
-######################
-*.log
-
-# VIM Swap Files
-######################
-*.swp
+# This .gitignore file is intended to be minimal.
+#
+# If you find that you need additional rules, such as IDE temporary
+# files, please do so either via a global .gitignore file (registered
+# with core.excludesFile), or by adding private repository-specific
+# rules to .git/info/exclude.  See https://git-scm.com/docs/gitignore
+# for more information.
 
 # Build directories
-######################
 build/
 build-*/
+docs/genrst/
 
 # Test failure outputs
-######################
 tests/results/*
 
 # Python cache files
-######################
 __pycache__/
-*.pyc
 
 # Customized Makefile/project overrides
-######################
 GNUmakefile
 user.props
 
-# Generated rst files
-######################
-genrst/
-
 # MacOS desktop metadata files
-######################
 .DS_Store

.gitmodules

@@ -13,7 +13,7 @@
 [submodule "lib/stm32lib"]
 	path = lib/stm32lib
 	url = https://github.com/micropython/stm32lib
-	branch = work-F4-1.13.1+F7-1.5.0+L4-1.3.0
+	branch = work-F0-1.9.0+F4-1.16.0+F7-1.7.0+G0-1.5.1+G4-1.3.0+H7-1.6.0+L0-1.11.2+L1-1.10.3+L4-1.17.0+WB-1.10.0+WL-1.1.0
 [submodule "lib/nrfx"]
 	path = lib/nrfx
 	url = https://github.com/NordicSemiconductor/nrfx.git
@@ -42,3 +42,17 @@
 [submodule "lib/pico-sdk"]
 	path = lib/pico-sdk
 	url = https://github.com/raspberrypi/pico-sdk.git
+[submodule "lib/fsp"]
+	path = lib/fsp
+	url = https://github.com/renesas/fsp.git
+[submodule "lib/wiznet"]
+	path = lib/wiznet5k
+	url = https://github.com/andrewleech/wiznet_ioLibrary_Driver.git
+	# Requires https://github.com/Wiznet/ioLibrary_Driver/pull/120
+	# url = https://github.com/Wiznet/ioLibrary_Driver.git
+[submodule "lib/cyw43-driver"]
+	path = lib/cyw43-driver
+	url = https://github.com/georgerobotics/cyw43-driver.git
+[submodule "lib/micropython-lib"]
+	path = lib/micropython-lib
+	url = https://github.com/micropython/micropython-lib.git

.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: local
+    hooks:
+      - id: codeformat
+        name: MicroPython codeformat.py for changed files
+        entry: tools/codeformat.py -v -f
+        language: python
+      - id: verifygitlog
+        name: MicroPython git commit message format checker
+        entry: tools/verifygitlog.py --check-file --ignore-rebase
+        language: python
+        verbose: true
+        stages: [commit-msg]

CODECONVENTIONS.md

@@ -65,6 +65,96 @@ changes to the correct style.  Without arguments this tool will reformat all
 source code (and may take some time to run).  Otherwise pass as arguments to
 the tool the files that changed and it will only reformat those.
 
+uncrustify
+==========
+
+Only [uncrustify](https://github.com/uncrustify/uncrustify) v0.71 or v0.72 can
+be used for MicroPython. Different uncrustify versions produce slightly
+different formatting, and the configuration file formats are often
+incompatible. v0.73 or newer *will not work*.
+
+Depending on your operating system version, it may be possible to install a pre-compiled
+uncrustify version:
+
+Ubuntu, Debian
+--------------
+
+Ubuntu versions 21.10 or 22.04LTS, and Debian versions bullseye or bookworm all
+include v0.72 so can be installed directly:
+
+```
+$ apt install uncrustify
+```
+
+Arch Linux
+----------
+
+The current Arch uncrustify version is too new. There is an [old Arch package
+for v0.72](https://archive.archlinux.org/packages/u/uncrustify/) that can be
+installed from the Arch Linux archive ([more
+information](https://wiki.archlinux.org/title/Downgrading_packages#Arch_Linux_Archive)). Use
+the [IgnorePkg feature](https://wiki.archlinux.org/title/Pacman#Skip_package_from_being_upgraded)
+to prevent it re-updating.
+
+Brew
+----
+
+This command may work, please raise a new Issue if it doesn't:
+
+```
+curl -L https://github.com/Homebrew/homebrew-core/raw/2b07d8192623365078a8b855a164ebcdf81494a6/Formula/uncrustify.rb > uncrustify.rb && brew install uncrustify.rb && rm uncrustify.rb
+```
+
+Automatic Pre-Commit Hooks
+==========================
+
+To have code formatting and commit message conventions automatically checked,
+a configuration file is provided for the [pre-commit](https://pre-commit.com/)
+tool.
+
+First install `pre-commit`, either from your system package manager or via
+`pip`. When installing `pre-commit` via pip, it is recommended to use a
+virtual environment. Other sources, such as Brew are also available, see
+[the docs](https://pre-commit.com/index.html#install) for details.
+
+```
+$ apt install pre-commit       # Ubuntu, Debian
+$ pacman -Sy python-precommit  # Arch Linux
+$ brew install pre-commit      # Brew
+$ pip install pre-commit       # PyPI
+```
+
+Next, install [uncrustify (see above)](#uncrustify). Other dependencies are managed by
+pre-commit automatically, but uncrustify needs to be installed and available on
+the PATH.
+
+Then, inside the MicroPython repository, register the git hooks for pre-commit
+by running:
+
+```
+$ pre-commit install --hook-type pre-commit --hook-type commit-msg
+```
+
+pre-commit will now automatically run during `git commit` for both code and
+commit message formatting.
+
+The same formatting checks will be run by CI for any Pull Request submitted to
+MicroPython. Pre-commit allows you to see any failure more quickly, and in many
+cases will automatically correct it in your local working copy.
+
+To unregister `pre-commit` from your MicroPython repository, run:
+
+```
+$ pre-commit uninstall --hook-type pre-commit --hook-type commit-msg
+```
+
+Tips:
+
+* To skip pre-commit checks on a single commit, use `git commit -n` (for
+  `--no-verify`).
+* To ignore the pre-commit message format check temporarily, start the commit
+  message subject line with "WIP" (for "Work In Progress").
+
 Python code conventions
 =======================
 

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2013-2022 Damien P. George
+Copyright (c) 2013-2023 Damien P. George
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -35,7 +35,6 @@ used during the build process and is not part of the compiled source code.
 
 / (MIT)
     /drivers
-        /cc3000 (BSD-3-clause)
         /cc3100 (BSD-3-clause)
         /wiznet5k (BSD-3-clause)
     /lib

README.md

@@ -15,167 +15,43 @@ code-base, including project-wide name changes and API changes.
 
 MicroPython implements the entire Python 3.4 syntax (including exceptions,
 `with`, `yield from`, etc., and additionally `async`/`await` keywords from
-Python 3.5). The following core datatypes are provided: `str` (including
-basic Unicode support), `bytes`, `bytearray`, `tuple`, `list`, `dict`, `set`,
-`frozenset`, `array.array`, `collections.namedtuple`, classes and instances.
-Builtin modules include `sys`, `time`, and `struct`, etc. Select ports have
-support for `_thread` module (multithreading). Note that only a subset of
-Python 3 functionality is implemented for the data types and modules.
+Python 3.5 and some select features from later versions). The following core
+datatypes are provided: `str`(including basic Unicode support), `bytes`,
+`bytearray`, `tuple`, `list`, `dict`, `set`, `frozenset`, `array.array`,
+`collections.namedtuple`, classes and instances. Builtin modules include
+`os`, `sys`, `time`, `re`, and `struct`, etc. Select ports have support for
+`_thread` module (multithreading), `socket` and `ssl` for networking, and
+`asyncio`. Note that only a subset of Python 3 functionality is implemented
+for the data types and modules.
 
-MicroPython can execute scripts in textual source form or from precompiled
-bytecode, in both cases either from an on-device filesystem or "frozen" into
-the MicroPython executable.
+MicroPython can execute scripts in textual source form (.py files) or from
+precompiled bytecode (.mpy files), in both cases either from an on-device
+filesystem or "frozen" into the MicroPython executable.
 
-See the repository http://github.com/micropython/pyboard for the MicroPython
-board (PyBoard), the officially supported reference electronic circuit board.
+MicroPython also provides a set of MicroPython-specific modules to access
+hardware-specific functionality and peripherals such as GPIO, Timers, ADC,
+DAC, PWM, SPI, I2C, CAN, Bluetooth, and USB.
 
-Major components in this repository:
-- py/ -- the core Python implementation, including compiler, runtime, and
-  core library.
-- mpy-cross/ -- the MicroPython cross-compiler which is used to turn scripts
-  into precompiled bytecode.
-- ports/unix/ -- a version of MicroPython that runs on Unix.
-- ports/stm32/ -- a version of MicroPython that runs on the PyBoard and similar
-  STM32 boards (using ST's Cube HAL drivers).
-- ports/minimal/ -- a minimal MicroPython port. Start with this if you want
-  to port MicroPython to another microcontroller.
-- tests/ -- test framework and test scripts.
-- docs/ -- user documentation in Sphinx reStructuredText format. Rendered
-  HTML documentation is available at http://docs.micropython.org.
+Getting started
+---------------
 
-Additional components:
-- ports/bare-arm/ -- a bare minimum version of MicroPython for ARM MCUs. Used
-  mostly to control code size.
-- ports/teensy/ -- a version of MicroPython that runs on the Teensy 3.1
-  (preliminary but functional).
-- ports/pic16bit/ -- a version of MicroPython for 16-bit PIC microcontrollers.
-- ports/cc3200/ -- a version of MicroPython that runs on the CC3200 from TI.
-- ports/esp8266/ -- a version of MicroPython that runs on Espressif's ESP8266 SoC.
-- ports/esp32/ -- a version of MicroPython that runs on Espressif's ESP32 SoC.
-- ports/nrf/ -- a version of MicroPython that runs on Nordic's nRF51 and nRF52 MCUs.
-- extmod/ -- additional (non-core) modules implemented in C.
-- tools/ -- various tools, including the pyboard.py module.
-- examples/ -- a few example Python scripts.
+See the [online documentation](https://docs.micropython.org/) for API
+references and information about using MicroPython and information about how
+it is implemented.
 
-The subdirectories above may include READMEs with additional info.
+We use [GitHub Discussions](https://github.com/micropython/micropython/discussions)
+as our forum, and [Discord](https://discord.gg/RB8HZSAExQ) for chat. These
+are great places to ask questions and advice from the community or to discuss your
+MicroPython-based projects.
 
-"make" is used to build the components, or "gmake" on BSD-based systems.
-You will also need bash, gcc, and Python 3.3+ available as the command `python3`
-(if your system only has Python 2.7 then invoke make with the additional option
-`PYTHON=python2`).
+For bugs and feature requests, please [raise an issue](https://github.com/micropython/micropython/issues/new/choose)
+and follow the templates there.
 
-The MicroPython cross-compiler, mpy-cross
------------------------------------------
-
-Most ports require the MicroPython cross-compiler to be built first.  This
-program, called mpy-cross, is used to pre-compile Python scripts to .mpy
-files which can then be included (frozen) into the firmware/executable for
-a port.  To build mpy-cross use:
-
-    $ cd mpy-cross
-    $ make
-
-The Unix version
-----------------
-
-The "unix" port requires a standard Unix environment with gcc and GNU make.
-x86 and x64 architectures are supported (i.e. x86 32- and 64-bit), as well
-as ARM and MIPS. Making full-featured port to another architecture requires
-writing some assembly code for the exception handling and garbage collection.
-Alternatively, fallback implementation based on setjmp/longjmp can be used.
-
-To build (see section below for required dependencies):
-
-    $ cd ports/unix
-    $ make submodules
-    $ make
-
-Then to give it a try:
-
-    $ ./micropython
-    >>> list(5 * x + y for x in range(10) for y in [4, 2, 1])
-
-Use `CTRL-D` (i.e. EOF) to exit the shell.
-Learn about command-line options (in particular, how to increase heap size
-which may be needed for larger applications):
-
-    $ ./micropython -h
-
-Run complete testsuite:
-
-    $ make test
-
-Unix version comes with a builtin package manager called upip, e.g.:
-
-    $ ./micropython -m upip install micropython-pystone
-    $ ./micropython -m pystone
-
-Browse available modules on
-[PyPI](https://pypi.python.org/pypi?%3Aaction=search&term=micropython).
-Standard library modules come from
-[micropython-lib](https://github.com/micropython/micropython-lib) project.
-
-External dependencies
----------------------
-
-Building MicroPython ports may require some dependencies installed.
-
-For Unix port, `libffi` library and `pkg-config` tool are required. On
-Debian/Ubuntu/Mint derivative Linux distros, install `build-essential`
-(includes toolchain and make), `libffi-dev`, and `pkg-config` packages.
-
-Other dependencies can be built together with MicroPython. This may
-be required to enable extra features or capabilities, and in recent
-versions of MicroPython, these may be enabled by default. To build
-these additional dependencies, in the port directory you're
-interested in (e.g. `ports/unix/`) first execute:
-
-    $ make submodules
-
-This will fetch all the relevant git submodules (sub repositories) that
-the port needs.  Use the same command to get the latest versions of
-submodules as they are updated from time to time. After that execute:
-
-    $ make deplibs
-
-This will build all available dependencies (regardless whether they
-are used or not). If you intend to build MicroPython with additional
-options (like cross-compiling), the same set of options should be passed
-to `make deplibs`. To actually enable/disable use of dependencies, edit
-`ports/unix/mpconfigport.mk` file, which has inline descriptions of the options.
-For example, to build SSL module (required for `upip` tool described above,
-and so enabled by default), `MICROPY_PY_USSL` should be set to 1.
-
-For some ports, building required dependences is transparent, and happens
-automatically.  But they still need to be fetched with the `make submodules`
-command.
-
-The STM32 version
------------------
-
-The "stm32" port requires an ARM compiler, arm-none-eabi-gcc, and associated
-bin-utils.  For those using Arch Linux, you need arm-none-eabi-binutils,
-arm-none-eabi-gcc and arm-none-eabi-newlib packages.  Otherwise, try here:
-https://launchpad.net/gcc-arm-embedded
-
-To build:
-
-    $ cd ports/stm32
-    $ make submodules
-    $ make
-
-You then need to get your board into DFU mode.  On the pyboard, connect the
-3V3 pin to the P1/DFU pin with a wire (on PYBv1.0 they are next to each other
-on the bottom left of the board, second row from the bottom).
-
-Then to flash the code via USB DFU to your device:
-
-    $ make deploy
-
-This will use the included `tools/pydfu.py` script.  If flashing the firmware
-does not work it may be because you don't have the correct permissions, and
-need to use `sudo make deploy`.
-See the README.md file in the ports/stm32/ directory for further details.
+For information about the [MicroPython pyboard](https://store.micropython.org/pyb-features),
+the officially supported board from the
+[original Kickstarter campaign](https://www.kickstarter.com/projects/214379695/micro-python-python-for-microcontrollers),
+see the [schematics and pinouts](http://github.com/micropython/pyboard) and
+[documentation](https://docs.micropython.org/en/latest/pyboard/quickref.html).
 
 Contributing
 ------------
@@ -186,3 +62,87 @@ productive, please be sure to follow the
 and the [Code Conventions](https://github.com/micropython/micropython/blob/master/CODECONVENTIONS.md).
 Note that MicroPython is licenced under the MIT license, and all contributions
 should follow this license.
+
+About this repository
+---------------------
+
+This repository contains the following components:
+- [py/](py/) -- the core Python implementation, including compiler, runtime, and
+  core library.
+- [mpy-cross/](mpy-cross/) -- the MicroPython cross-compiler which is used to turn scripts
+  into precompiled bytecode.
+- [ports/](ports/) -- platform-specific code for the various ports and architectures that MicroPython runs on.
+- [lib/](lib/) -- submodules for external dependencies.
+- [tests/](tests/) -- test framework and test scripts.
+- [docs/](docs/) -- user documentation in Sphinx reStructuredText format. This is used to generate the [online documentation](http://docs.micropython.org).
+- [extmod/](extmod/) -- additional (non-core) modules implemented in C.
+- [tools/](tools/) -- various tools, including the pyboard.py module.
+- [examples/](examples/) -- a few example Python scripts.
+
+"make" is used to build the components, or "gmake" on BSD-based systems.
+You will also need bash, gcc, and Python 3.3+ available as the command `python3`
+(if your system only has Python 2.7 then invoke make with the additional option
+`PYTHON=python2`). Some ports (rp2 and esp32) additionally use CMake.
+
+Supported platforms & architectures
+-----------------------------------
+
+MicroPython runs on a wide range of microcontrollers, as well as on Unix-like
+(including Linux, BSD, macOS, WSL) and Windows systems.
+
+Microcontroller targets can be as small as 256kiB flash + 16kiB RAM, although
+devices with at least 512kiB flash + 128kiB RAM allow a much more
+full-featured experience.
+
+The [Unix](ports/unix) and [Windows](ports/windows) ports allow both
+development and testing of MicroPython itself, as well as providing
+lightweight alternative to CPython on these platforms (in particular on
+embedded Linux systems).
+
+The ["minimal"](ports/minimal) port provides an example of a very basic
+MicroPython port and can be compiled as both a standalone Linux binary as
+well as for ARM Cortex M4. Start with this if you want to port MicroPython to
+another microcontroller. Additionally the ["bare-arm"](ports/bare-arm) port
+is an example of the absolute minimum configuration, and is used to keep
+track of the code size of the core runtime and VM.
+
+In addition, the following ports are provided in this repository:
+ - [cc3200](ports/cc3200) -- Texas Instruments CC3200 (including PyCom WiPy).
+ - [esp32](ports/esp32) -- Espressif ESP32 SoC (including ESP32S2, ESP32S3, ESP32C3).
+ - [esp8266](ports/esp8266) -- Espressif ESP8266 SoC.
+ - [mimxrt](ports/mimxrt) -- NXP m.iMX RT (including Teensy 4.x).
+ - [nrf](ports/nrf) -- Nordic Semiconductor nRF51 and nRF52.
+ - [pic16bit](ports/pic16bit) -- Microchip PIC 16-bit.
+ - [powerpc](ports/powerpc) -- IBM PowerPC (including Microwatt)
+ - [qemu-arm](ports/qemu-arm) -- QEMU-based emulated target, for testing)
+ - [renesas-ra](ports/renesas-ra) -- Renesas RA family.
+ - [rp2](ports/rp2) -- Raspberry Pi RP2040 (including Pico and Pico W).
+ - [samd](ports/samd) -- Microchip (formerly Atmel) SAMD21 and SAMD51.
+ - [stm32](ports/stm32) -- STMicroelectronics STM32 family (including F0, F4, F7, G0, G4, H7, L0, L4, WB)
+ - [teensy](ports/teensy) -- Teensy 3.x.
+ - [webassembly](ports/webassembly) -- Emscripten port targeting browsers and NodeJS.
+ - [zephyr](ports/zephyr) -- Zephyr RTOS.
+
+The MicroPython cross-compiler, mpy-cross
+-----------------------------------------
+
+Most ports require the [MicroPython cross-compiler](mpy-cross) to be built
+first.  This program, called mpy-cross, is used to pre-compile Python scripts
+to .mpy files which can then be included (frozen) into the
+firmware/executable for a port.  To build mpy-cross use:
+
+    $ cd mpy-cross
+    $ make
+
+External dependencies
+---------------------
+
+The core MicroPython VM and runtime has no external dependencies, but a given
+port might depend on third-party drivers or vendor HALs. This repository
+includes [several submodules](lib/) linking to these external dependencies.
+Before compiling a given port, use
+
+    $ cd ports/name
+    $ make submodules
+
+to ensure that all required submodules are initialised.

docs/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line.
 PYTHON        = python3
-SPHINXOPTS    = -W --keep-going
+SPHINXOPTS    = -W --keep-going -j auto
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build/$(MICROPY_PORT)

docs/README.md

@@ -47,7 +47,7 @@ This can be achieved with:
 
     make latexpdf
 
-but require rather complete install of LaTeX with various extensions. On
-Debian/Ubuntu, try (500MB+ download):
+but requires a rather complete install of LaTeX with various extensions. On
+Debian/Ubuntu, try (1GB+ download):
 
-    apt-get install texlive-latex-recommended texlive-latex-extra
+    apt install texlive-latex-recommended texlive-latex-extra texlive-xetex texlive-fonts-extra cm-super xindy

docs/conf.py

@@ -33,6 +33,7 @@ html_context = {
     'downloads':[
         ('PDF', url_pattern % micropy_version + '/micropython-docs.pdf'),
     ],
+    'is_release': micropy_version != 'latest',
 }
 
 
@@ -66,7 +67,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'MicroPython'
-copyright = '- The MicroPython Documentation is Copyright © 2014-2022, Damien P. George, Paul Sokolovsky, and contributors'
+copyright = '- The MicroPython Documentation is Copyright © 2014-2023, Damien P. George, Paul Sokolovsky, and contributors'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -74,7 +75,7 @@ copyright = '- The MicroPython Documentation is Copyright © 2014-2022, Damien P
 #
 # We don't follow "The short X.Y version" vs "The full version, including alpha/beta/rc tags"
 # breakdown, so use the same version identifier for both to avoid confusion.
-version = release = '1.18'
+version = release = micropy_version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -166,6 +167,10 @@ html_favicon = 'static/favicon.ico'
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['static']
 
+# Add a custom CSS file for HTML generation
+html_css_files = [
+    'custom.css',
+]
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.
@@ -259,6 +264,8 @@ latex_documents = [
 # If false, no module index is generated.
 #latex_domain_indices = True
 
+# Enable better Unicode support so that `make latexpdf` doesn't fail
+latex_engine = "xelatex"
 
 # -- Options for manual page output ---------------------------------------
 

docs/develop/cmodules.rst

@@ -49,9 +49,17 @@ A MicroPython user C module is a directory with the following files:
   in your ``micropython.mk`` to a local make variable,
   eg ``EXAMPLE_MOD_DIR := $(USERMOD_DIR)``
 
-  Your ``micropython.mk`` must add your modules source files relative to your
-  expanded copy of ``$(USERMOD_DIR)`` to ``SRC_USERMOD``, eg
-  ``SRC_USERMOD += $(EXAMPLE_MOD_DIR)/example.c``
+  Your ``micropython.mk`` must add your modules source files to the
+  ``SRC_USERMOD_C`` or ``SRC_USERMOD_LIB_C`` variables. The former will be
+  processed for ``MP_QSTR_`` and ``MP_REGISTER_MODULE`` definitions, the latter
+  will not (e.g. helpers and library code that isn't MicroPython-specific).
+  These paths should include your expaned copy of ``$(USERMOD_DIR)``, e.g.::
+
+    SRC_USERMOD_C += $(EXAMPLE_MOD_DIR)/modexample.c
+    SRC_USERMOD_LIB_C += $(EXAMPLE_MOD_DIR)/utils/algorithm.c
+
+  Similarly, use ``SRC_USERMOD_CXX`` and ``SRC_USERMOD_LIB_CXX`` for C++
+  source files.
 
   If you have custom compiler options (like ``-I`` to add directories to search
   for header files), these should be added to ``CFLAGS_USERMOD`` for C code
@@ -87,9 +95,12 @@ A MicroPython user C module is a directory with the following files:
 Basic example
 -------------
 
-This simple module named ``cexample`` provides a single function
-``cexample.add_ints(a, b)`` which adds the two integer args together and returns
-the result. It can be found in the MicroPython source tree
+The ``cexample`` module provides examples for a function and a class. The
+``cexample.add_ints(a, b)`` function adds two integer args together and returns
+the result. The ``cexample.Timer()`` type creates timers that can be used to
+measure the elapsed time since the object is instantiated.
+
+The module can be found in the MicroPython source tree
 `in the examples directory <https://github.com/micropython/micropython/tree/master/examples/usercmodule/cexample>`_
 and has a source file and a Makefile fragment with content as described above::
 
@@ -221,23 +232,25 @@ as described above.
 If a module is not enabled by default then the corresponding C preprocessor macro
 must be enabled.  This macro name can be found by searching for the ``MP_REGISTER_MODULE``
 line in the module's source code (it usually appears at the end of the main source file).
-The third argument to ``MP_REGISTER_MODULE`` is the macro name, and this must be set
-to 1 using ``CFLAGS_EXTRA`` to make the module available.  If the third argument is just
-the number 1 then the module is enabled by default.
+This macro should be surrounded by a ``#if X`` / ``#endif`` pair, and the configuration
+option ``X`` must be set to 1 using ``CFLAGS_EXTRA`` to make the module available.  If
+there is no ``#if X`` / ``#endif`` pair then the module is enabled by default.
 
 For example, the ``examples/usercmodule/cexample`` module is enabled by default so
 has the following line in its source code:
 
   .. code-block:: c
 
-      MP_REGISTER_MODULE(MP_QSTR_cexample, example_user_cmodule, 1);
+      MP_REGISTER_MODULE(MP_QSTR_cexample, example_user_cmodule);
 
 Alternatively, to make this module disabled by default but selectable through
 a preprocessor configuration option, it would be:
 
   .. code-block:: c
 
-      MP_REGISTER_MODULE(MP_QSTR_cexample, example_user_cmodule, MODULE_CEXAMPLE_ENABLED);
+      #if MODULE_CEXAMPLE_ENABLED
+      MP_REGISTER_MODULE(MP_QSTR_cexample, example_user_cmodule);
+      #endif
 
 In this case the module is enabled by adding ``CFLAGS_EXTRA=-DMODULE_CEXAMPLE_ENABLED=1``
 to the ``make`` command, or editing ``mpconfigport.h`` or ``mpconfigboard.h`` to add
@@ -262,3 +275,13 @@ can now be accessed in Python just like any other builtin module, e.g.
     import cexample
     print(cexample.add_ints(1, 3))
     # should display 4
+
+.. code-block:: python
+
+    from cexample import Timer
+    from time import sleep_ms
+
+    watch = Timer()
+    sleep_ms(1000)
+    print(watch.time())
+    # should display approximately 1000

docs/develop/compiler.rst

@@ -147,10 +147,17 @@ The most relevant method you should know about is this:
 .. code-block:: c
 
    mp_obj_t mp_compile(mp_parse_tree_t *parse_tree, qstr source_file, bool is_repl) {
+       // Create a context for this module, and set its globals dict.
+       mp_module_context_t *context = m_new_obj(mp_module_context_t);
+       context->module.globals = mp_globals_get();
+
        // Compile the input parse_tree to a raw-code structure.
-       mp_raw_code_t *rc = mp_compile_to_raw_code(parse_tree, source_file, is_repl);
+       mp_compiled_module_t cm;
+       cm.context = context;
+       mp_compile_to_raw_code(parse_tree, source_file, is_repl, &cm);
+
        // Create and return a function object that executes the outer module.
-       return mp_make_function_from_raw_code(rc, MP_OBJ_NULL, MP_OBJ_NULL);
+       return mp_make_function_from_raw_code(cm.rc, cm.context, NULL);
    }
 
 The compiler compiles the code in four passes: scope, stack size, code size and emit.

docs/develop/gettingstarted.rst

@@ -103,7 +103,7 @@ For the stm32 port, the ARM cross-compiler is required:
    $ sudo apt-get install arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib
 
 See the `ARM GCC
-toolchain <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm>`_
+toolchain <https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads>`_
 for the latest details.
 
 Python is also required. Python 2 is supported for now, but we recommend using Python 3.
@@ -322,7 +322,8 @@ tests
 
 tools
 
-  Contains helper tools including the ``upip`` and the ``pyboard.py`` module.
+  Contains scripts used by the build and CI process, as well as user tools such
+  as ``pyboard.py`` and ``mpremote``.
 
 examples
 

docs/develop/library.rst

@@ -64,7 +64,7 @@ hypothetical new module ``subsystem`` in the file ``modsubsystem.c``:
        .globals = (mp_obj_dict_t *)&mp_module_subsystem_globals,
    };
 
-   MP_REGISTER_MODULE(MP_QSTR_subsystem, mp_module_subsystem, MICROPY_PY_SUBSYSTEM);
+   MP_REGISTER_MODULE(MP_QSTR_subsystem, mp_module_subsystem);
 
    #endif
 

docs/develop/natmod.rst

@@ -34,6 +34,7 @@ options for the ``ARCH`` variable, see below):
 
 * ``x86`` (32 bit)
 * ``x64`` (64 bit x86)
+* ``armv6m`` (ARM Thumb, eg Cortex-M0)
 * ``armv7m`` (ARM Thumb 2, eg Cortex-M3)
 * ``armv7emsp`` (ARM Thumb 2, single precision float, eg Cortex-M4F, Cortex-M7)
 * ``armv7emdp`` (ARM Thumb 2, double precision float, eg Cortex-M7)
@@ -171,7 +172,7 @@ The file ``Makefile`` contains:
     # Source files (.c or .py)
     SRC = factorial.c
 
-    # Architecture to build for (x86, x64, armv7m, xtensa, xtensawin)
+    # Architecture to build for (x86, x64, armv6m, armv7m, xtensa, xtensawin)
     ARCH = x64
 
     # Include to get the rules for compiling and linking the module

docs/develop/optimizations.rst

@@ -25,6 +25,8 @@ into the firmware image as part of the main firmware compilation process, which
 the bytecode will be executed from ROM. This can lead to a significant memory saving, and
 reduce heap fragmentation.
 
+See :ref:`manifest` for more information.
+
 Variables
 ---------
 

docs/develop/porting.rst

@@ -95,10 +95,11 @@ We also need a Makefile at this point for the port:
 
    # Include py core make definitions.
    include $(TOP)/py/py.mk
+   include $(TOP)/extmod/extmod.mk
 
    # Set CFLAGS and libraries.
-   CFLAGS = -I. -I$(BUILD) -I$(TOP)
-   LIBS = -lm
+   CFLAGS += -I. -I$(BUILD) -I$(TOP)
+   LIBS += -lm
 
    # Define the required source files.
    SRC_C = \
@@ -146,6 +147,9 @@ The following is an example of an ``mpconfigport.h`` file:
    #define MICROPY_ERROR_REPORTING                 (MICROPY_ERROR_REPORTING_TERSE)
    #define MICROPY_FLOAT_IMPL                      (MICROPY_FLOAT_IMPL_FLOAT)
 
+   // Enable u-modules to be imported with their standard name, like sys.
+   #define MICROPY_MODULE_WEAK_LINKS               (1)
+
    // Fine control over Python builtins, classes, modules, etc.
    #define MICROPY_PY_ASYNC_AWAIT                  (0)
    #define MICROPY_PY_BUILTINS_SET                 (0)
@@ -170,9 +174,6 @@ The following is an example of an ``mpconfigport.h`` file:
 
    #define MP_STATE_PORT MP_STATE_VM
 
-   #define MICROPY_PORT_ROOT_POINTERS \
-       const char *readline_hist[8];
-
 This configuration file contains machine-specific configurations including aspects like if different
 MicroPython features should be enabled e.g. ``#define MICROPY_ENABLE_GC (1)``. Making this Setting
 ``(0)`` disables the feature.
@@ -277,12 +278,7 @@ To add a custom module like ``myport``, first add the module definition in a fil
        .globals = (mp_obj_dict_t *)&myport_module_globals,
    };
 
-   MP_REGISTER_MODULE(MP_QSTR_myport, myport_module, 1);
-
-Note: the "1" as the third argument in ``MP_REGISTER_MODULE`` enables this new module
-unconditionally. To allow it to be conditionally enabled, replace the "1" by
-``MICROPY_PY_MYPORT`` and then add ``#define MICROPY_PY_MYPORT (1)`` in ``mpconfigport.h``
-accordingly.
+   MP_REGISTER_MODULE(MP_QSTR_myport, myport_module);
 
 You will also need to edit the Makefile to add ``modmyport.c`` to the ``SRC_C`` list, and
 a new line adding the same file to ``SRC_QSTR`` (so qstrs are searched for in this new file),
@@ -296,7 +292,7 @@ like this:
        mphalport.c \
        ...
 
-   SRC_QSTR += modport.c
+   SRC_QSTR += modmyport.c
 
 If all went correctly then, after rebuilding, you should be able to import the new module:
 

docs/differences/index_template.txt

@@ -13,6 +13,7 @@ above.  The sections below describe the current status of these features.
     ../differences/python_37.rst
     ../differences/python_38.rst
     ../differences/python_39.rst
+    ../differences/python_310.rst
 
 For the features of Python that are implemented by MicroPython, there are
 sometimes differences in their behaviour compared to standard Python.  The

docs/differences/python_310.rst

@@ -0,0 +1,238 @@
+.. _python_310:
+
+Python 3.10
+===========
+
+Python 3.10.0 (final) was released on the 4 October 2021. The Features for 3.10 are
+defined in `PEP 619 <https://www.python.org/dev/peps/pep-0619/#features-for-3-10>`_
+and a detailed description of the changes can be found in
+`What's New in Python 3.10 <https://docs.python.org/3/whatsnew/3.10.html>`_.
+
+.. table::
+  :widths: 20 60 20
+
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | **New syntax features**                                                                                     | **Status**   |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 634 <https://www.python.org/dev/peps/pep-0634/>`_ | Structural Pattern Matching: Specification         | [#spm]_      |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 635 <https://www.python.org/dev/peps/pep-0635/>`_ | Structural Pattern Matching: Motivation and        | [#spm]_      |
+  |                                                        | Rationale                                          |              |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 636 <https://www.python.org/dev/peps/pep-0636/>`_ | Structural Pattern Matching: Tutorial              | [#spm]_      |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `bpo-12782                                             | Parenthesized context managers are now officially  |              |
+  | <https://github.com/python/cpython/issues/56991>`_     | allowed                                            |              |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | **New features in the standard library**                                                                                   |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 618 <https://www.python.org/dev/peps/pep-0618/>`_ | Add Optional Length-Checking To zip                |              |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | **Interpreter improvements**                                                                                               |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 626 <https://www.python.org/dev/peps/pep-0626/>`_ | Precise line numbers for debugging and other tools |              |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | **New typing features**                                                                                                    |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 604 <https://www.python.org/dev/peps/pep-0604/>`_ | Allow writing union types as X | Y                 |              |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 613 <https://www.python.org/dev/peps/pep-0613/>`_ | Explicit Type Aliases                              |              |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 612 <https://www.python.org/dev/peps/pep-0612/>`_ | Parameter Specification Variables                  |              |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | **Important deprecations, removals or restrictions**                                                                       |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 644 <https://www.python.org/dev/peps/pep-0644/>`_ | Require OpenSSL 1.1.1 or newer                     |              |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 632 <https://www.python.org/dev/peps/pep-0632/>`_ | Deprecate distutils module.                        | Not relevant |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 623 <https://www.python.org/dev/peps/pep-0623/>`_ | Deprecate and prepare for the removal of the wstr  | Not relevant |
+  |                                                        | member in PyUnicodeObject.                         |              |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 624 <https://www.python.org/dev/peps/pep-0624/>`_ | Remove Py_UNICODE encoder APIs                     | Not relevant |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 597 <https://www.python.org/dev/peps/pep-0597/>`_ | Add optional EncodingWarning                       |              |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+
+
+Other Language Changes:
+
+.. table::
+  :widths: 90 10
+
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | The :class:`int` type has a new method :meth:`int.bit_count`, returning the                                 |               |
+  | number of ones in the binary expansion of a given integer, also known                                       |               |
+  | as the population count.                                                                                    |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | The views returned by :meth:`dict.keys`, :meth:`dict.values` and                                            |               |
+  | :meth:`dict.items` now all have a ``mapping`` attribute that gives a                                        |               |
+  | :class:`types.MappingProxyType` object wrapping the original                                                |               |
+  | dictionary.                                                                                                 |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | :pep:`618`: The :func:`zip` function now has an optional ``strict`` flag, used                              |               |
+  | to require that all the iterables have an equal length.                                                     |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Builtin and extension functions that take integer arguments no longer accept                                |               |
+  | :class:`~decimal.Decimal`\ s, :class:`~fractions.Fraction`\ s and other                                     |               |
+  | objects that can be converted to integers only with a loss (e.g. that have                                  |               |
+  | the :meth:`~object.__int__` method but do not have the                                                      |               |
+  | :meth:`~object.__index__` method).                                                                          |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | If :func:`object.__ipow__` returns :const:`NotImplemented`, the operator will                               |               |
+  | correctly fall back to :func:`object.__pow__` and :func:`object.__rpow__` as expected.                      |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Assignment expressions can now be used unparenthesized within set literals                                  |               |
+  | and set comprehensions, as well as in sequence indexes (but not slices).                                    |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Functions have a new ``__builtins__`` attribute which is used to look for                                   |               |
+  | builtin symbols when a function is executed, instead of looking into                                        |               |
+  | ``__globals__['__builtins__']``. The attribute is initialized from                                          |               |
+  | ``__globals__["__builtins__"]`` if it exists, else from the current builtins.                               |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Two new builtin functions -- :func:`aiter` and :func:`anext` have been added                                |               |
+  | to provide asynchronous counterparts to :func:`iter` and :func:`next`,                                      |               |
+  | respectively.                                                                                               |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Static methods (:func:`@staticmethod <staticmethod>`) and class methods                                     |               |
+  | (:func:`@classmethod <classmethod>`) now inherit the method attributes                                      |               |
+  | (``__module__``, ``__name__``, ``__qualname__``, ``__doc__``,                                               |               |
+  | ``__annotations__``) and have a new ``__wrapped__`` attribute.                                              |               |
+  | Moreover, static methods are now callable as regular functions.                                             |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Annotations for complex targets (everything beside ``simple name`` targets                                  |               |
+  | defined by :pep:`526`) no longer cause any runtime effects with ``from __future__ import annotations``.     |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Class and module objects now lazy-create empty annotations dicts on demand.                                 |               |
+  | The annotations dicts are stored in the object’s ``__dict__`` for                                           |               |
+  | backwards compatibility.  This improves the best practices for working                                      |               |
+  | with ``__annotations__``.                                                                                   |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Annotations consist of ``yield``, ``yield from``, ``await`` or named expressions                            |               |
+  | are now forbidden under ``from __future__ import annotations`` due to their side                            |               |
+  | effects.                                                                                                    |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Usage of unbound variables, ``super()`` and other expressions that might                                    |               |
+  | alter the processing of symbol table as annotations are now rendered                                        |               |
+  | effectless under ``from __future__ import annotations``.                                                    |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Hashes of NaN values of both :class:`float` type and                                                        |               |
+  | :class:`decimal.Decimal` type now depend on object identity. Formerly, they                                 |               |
+  | always hashed to ``0`` even though NaN values are not equal to one another.                                 |               |
+  | This caused potentially quadratic runtime behavior due to excessive hash                                    |               |
+  | collisions when creating dictionaries and sets containing multiple NaNs.                                    |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | A :exc:`SyntaxError` (instead of a :exc:`NameError`) will be raised when deleting                           |               |
+  | the :const:`__debug__` constant.                                                                            |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | :exc:`SyntaxError` exceptions now have ``end_lineno`` and                                                   |               |
+  | ``end_offset`` attributes.  They will be ``None`` if not determined.                                        |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+
+Changes to built-in modules:
+
+.. table::
+  :widths: 90 10
+
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `asyncio <https://docs.python.org/3/whatsnew/3.10.html#asyncio>`_                                                             |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add missing :meth:`~asyncio.events.AbstractEventLoop.connect_accepted_socket`                                 |               |
+  | method.                                                                                                       |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `array <https://docs.python.org/3/whatsnew/3.10.html#array>`_                                                                 |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | The :meth:`~array.array.index` method of :class:`array.array` now has                                         |               |
+  | optional *start* and *stop* parameters.                                                                       |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `gc <https://docs.python.org/3/whatsnew/3.10.html#gc>`_                                                                       |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add audit hooks for :func:`gc.get_objects`, :func:`gc.get_referrers` and                                      |               |
+  | :func:`gc.get_referents`.                                                                                     |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `hashlib <https://docs.python.org/3/whatsnew/3.10.html#hashlib>`_                                                             |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | The hashlib module requires OpenSSL 1.1.1 or newer.                                                           |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | The hashlib module has preliminary support for OpenSSL 3.0.0.                                                 |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | The pure-Python fallback of :func:`~hashlib.pbkdf2_hmac` is deprecated. In                                    |               |
+  | the future PBKDF2-HMAC will only be available when Python has been built with                                 |               |
+  | OpenSSL support.                                                                                              |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `os <https://docs.python.org/3/whatsnew/3.10.html#os>`_                                                                       |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add :func:`os.cpu_count()` support for VxWorks RTOS.                                                          |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add a new function :func:`os.eventfd` and related helpers to wrap the                                         |               |
+  | ``eventfd2`` syscall on Linux.                                                                                |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add :func:`os.splice()` that allows to move data between two file                                             |               |
+  | descriptors without copying between kernel address space and user                                             |               |
+  | address space, where one of the file descriptors must refer to a                                              |               |
+  | pipe.                                                                                                         |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add :data:`~os.O_EVTONLY`, :data:`~os.O_FSYNC`, :data:`~os.O_SYMLINK`                                         |               |
+  | and :data:`~os.O_NOFOLLOW_ANY` for macOS.                                                                     |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `platform <https://docs.python.org/3/whatsnew/3.10.html#platform>`_                                                           |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add :func:`platform.freedesktop_os_release()` to retrieve operation system                                    |               |
+  | identification from `freedesktop.org os-release                                                               |               |
+  | <https://www.freedesktop.org/software/systemd/man/os-release.html>`_ standard file.                           |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `socket <https://docs.python.org/3/whatsnew/3.10.html#socket>`_                                                               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | The exception :exc:`socket.timeout` is now an alias of :exc:`TimeoutError`.                                   |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add option to create MPTCP sockets with ``IPPROTO_MPTCP``.                                                    |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add ``IP_RECVTOS`` option to receive the type of service (ToS) or DSCP/ECN fields.                            |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `ssl <https://docs.python.org/3/whatsnew/3.10.html#ssl>`_                                                                     |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | The ssl module requires OpenSSL 1.1.1 or newer.                                                               |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | The ssl module has preliminary support for OpenSSL 3.0.0 and new option                                       |               |
+  | :data:`~ssl.OP_IGNORE_UNEXPECTED_EOF`.                                                                        |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Deprecated function and use of deprecated constants now result in                                             |               |
+  | a :exc:`DeprecationWarning`. :attr:`ssl.SSLContext.options` has                                               |               |
+  | :data:`~ssl.OP_NO_SSLv2` and :data:`~ssl.OP_NO_SSLv3` set by default and                                      |               |
+  | therefore cannot warn about setting the flag again.                                                           |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | The ssl module now has more secure default settings. Ciphers without forward                                  |               |
+  | secrecy or SHA-1 MAC are disabled by default. Security level 2 prohibits                                      |               |
+  | weak RSA, DH, and ECC keys with less than 112 bits of security.                                               |               |
+  | :class:`~ssl.SSLContext` defaults to minimum protocol version TLS 1.2.                                        |               |
+  | Settings are based on Hynek Schlawack's research.                                                             |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | The deprecated protocols SSL 3.0, TLS 1.0, and TLS 1.1 are no longer                                          |               |
+  | officially supported. Python does not block them actively. However                                            |               |
+  | OpenSSL build options, distro configurations, vendor patches, and cipher                                      |               |
+  | suites may prevent a successful handshake.                                                                    |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add a *timeout* parameter to the :func:`ssl.get_server_certificate` function.                                 |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | The ssl module uses heap-types and multi-phase initialization.                                                |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | A new verify flag :data:`~ssl.VERIFY_X509_PARTIAL_CHAIN` has been added.                                      |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `sys <https://docs.python.org/3/whatsnew/3.10.html#sys>`_                                                                     |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add :data:`sys.orig_argv` attribute: the list of the original command line                                    |               |
+  | arguments passed to the Python executable.                                                                    |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add :data:`sys.stdlib_module_names`, containing the list of the standard library                              |               |
+  | module names.                                                                                                 |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `_thread <https://docs.python.org/3/whatsnew/3.10.html#_thread>`_                                                             |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | :func:`_thread.interrupt_main` now takes an optional signal number to                                         |               |
+  | simulate (the default is still :data:`signal.SIGINT`).                                                        |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+
+.. rubric:: Notes
+
+.. [#spm] The structural pattern matching feature is discussed in `issue #7847 <https://github.com/micropython/micropython/issues/7847>`_.
+

docs/differences/python_35.rst

@@ -5,55 +5,60 @@ Python 3.5
 
 Below is a list of finalised/accepted PEPs for Python 3.5 grouped into their impact to MicroPython.
 
-   +----------------------------------------------------------------------------------------------------------+---------------+
-   | **Extensions to the syntax:**                                                                            | **Status**    |
-   +--------------------------------------------------------+-------------------------------------------------+---------------+
-   | `PEP 448 <https://www.python.org/dev/peps/pep-0448/>`_ | additional unpacking generalizations            |               |
-   +--------------------------------------------------------+-------------------------------------------------+---------------+
-   | `PEP 465 <https://www.python.org/dev/peps/pep-0465/>`_ | a new matrix multiplication operator            | Completed     |
-   +--------------------------------------------------------+-------------------------------------------------+---------------+
-   | `PEP 492 <https://www.python.org/dev/peps/pep-0492/>`_ | coroutines with async and await syntax          | Completed     |
-   +--------------------------------------------------------+-------------------------------------------------+---------------+
-   | **Extensions and changes to runtime:**                                                                                   |
-   +--------------------------------------------------------+-------------------------------------------------+---------------+
-   | `PEP 461 <https://www.python.org/dev/peps/pep-0461/>`_ | % formatting for binary strings                 | Completed     |
-   +--------------------------------------------------------+-------------------------------------------------+---------------+
-   | `PEP 475 <https://www.python.org/dev/peps/pep-0475/>`_ | retrying system calls that fail with EINTR      | Completed     |
-   +--------------------------------------------------------+-------------------------------------------------+---------------+
-   | `PEP 479 <https://www.python.org/dev/peps/pep-0479/>`_ | change StopIteration handling inside generators | Completed     |
-   +--------------------------------------------------------+-------------------------------------------------+---------------+
-   | **Standard library changes:**                                                                                            |
-   +--------------------------------------------------------+-------------------------------------------------+---------------+
-   | `PEP 471 <https://www.python.org/dev/peps/pep-0471/>`_ | os.scandir()                                    |               |
-   +--------------------------------------------------------+-------------------------------------------------+---------------+
-   | `PEP 485 <https://www.python.org/dev/peps/pep-0485/>`_ | math.isclose(), a function for testing          | Completed     |
-   |                                                        | approximate equality                            |               |
-   +--------------------------------------------------------+-------------------------------------------------+---------------+
-   | **Miscellaneous changes:**                                                                                               |
-   +--------------------------------------------------------+-------------------------------------------------+---------------+
-   | `PEP 441 <https://www.python.org/dev/peps/pep-0441/>`_ | improved Python zip application support         |               |
-   +--------------------------------------------------------+-------------------------------------------------+---------------+
-   | `PEP 486 <https://www.python.org/dev/peps/pep-0486/>`_ | make the Python Laucher aware of virtual        |               |
-   |                                                        | environments                                    |               |
-   +--------------------------------------------------------+-------------------------------------------------+---------------+
-   | `PEP 484 <https://www.python.org/dev/peps/pep-0484/>`_ | type hints (advisory only)                      | In Progress   |
-   +--------------------------------------------------------+-------------------------------------------------+---------------+
-   | `PEP 488 <https://www.python.org/dev/peps/pep-0488/>`_ | elimination of PYO files                        | Not relevant  |
-   +--------------------------------------------------------+-------------------------------------------------+---------------+
-   | `PEP 489 <https://www.python.org/dev/peps/pep-0489/>`_ | redesigning extension module loading            |               |
-   +--------------------------------------------------------+-------------------------------------------------+---------------+
+.. table::
+  :widths: 30 50 20
 
+  +--------------------------------------------------------------------------------------------------------------+--------------------+
+  | **Extensions to the syntax**                                                                                 | **Status**         |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 448 <https://www.python.org/dev/peps/pep-0448/>`_ | Additional unpacking generalizations                | Partial            |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 465 <https://www.python.org/dev/peps/pep-0465/>`_ | A new matrix multiplication operator                | Complete           |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 492 <https://www.python.org/dev/peps/pep-0492/>`_ | Coroutines with ``async`` and ``await`` syntax      | Complete           |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | **Extensions and changes to runtime**                                                                                             |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 461 <https://www.python.org/dev/peps/pep-0461/>`_ | % formatting for binary strings                     | Complete           |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 475 <https://www.python.org/dev/peps/pep-0475/>`_ | Retrying system calls that fail with ``EINTR``      | Complete           |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 479 <https://www.python.org/dev/peps/pep-0479/>`_ | Change ``StopIteration`` handling inside generators | Complete           |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | **Standard library changes**                                                                                                      |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 471 <https://www.python.org/dev/peps/pep-0471/>`_ | ``os.scandir()``                                    |                    |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 485 <https://www.python.org/dev/peps/pep-0485/>`_ | ``math.isclose()``, a function for testing          | Complete           |
+  |                                                        | approximate equality                                |                    |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | **Miscellaneous changes**                                                                                                         |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 441 <https://www.python.org/dev/peps/pep-0441/>`_ | Improved Python zip application support             |                    |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 486 <https://www.python.org/dev/peps/pep-0486/>`_ | Make the Python Launcher aware of virtual           | Not relevant       |
+  |                                                        | environments                                        |                    |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 484 <https://www.python.org/dev/peps/pep-0484/>`_ | Type hints (advisory only)                          | Complete [#fth]_   |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 488 <https://www.python.org/dev/peps/pep-0488/>`_ | Elimination of PYO files                            | Not relevant       |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 489 <https://www.python.org/dev/peps/pep-0489/>`_ | Redesigning extension module loading                |                    |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
 
 Other Language Changes:
 
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | Added the *namereplace* error handlers. The *backslashreplace* error handlers now work with decoding and  |               |
-   | translating.                                                                                              |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | Property docstrings are now writable. This is especially useful for collections.namedtuple() docstrings   |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | Circular imports involving relative imports are now supported.                                            |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
+.. table::
+  :widths: 90 10
+
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | Added the *namereplace* error handlers. The *backslashreplace* error handlers now work with decoding and  |               |
+  | translating.                                                                                              |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | Property docstrings are now writable. This is especially useful for collections.namedtuple() docstrings   |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | Circular imports involving relative imports are now supported.                                            |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
 
 
 New Modules:
@@ -65,117 +70,124 @@ New Modules:
 
 Changes to built-in modules:
 
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | `collections <https://docs.python.org/3/whatsnew/3.5.html#collections>`_                                                  |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | The *OrderedDict* class is now implemented in C, which makes it 4 to 100 times faster.                    |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | *OrderedDict.items()* , *OrderedDict.keys()* , *OrderedDict.values()* views now support reversed()        |               |
-   | iteration.                                                                                                |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | The deque class now defines *index()*, *insert()*, and *copy()*, and supports the + and * operators.      |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | Docstrings produced by namedtuple() can now be updated.                                                   |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | The UserString class now implements the *__getnewargs__()*, *__rmod__()*, *casefold()*, *format_map()*,   |               |
-   | *isprintable()*, and *maketrans()* methods to match the corresponding methods of str.                     |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | `heapq <https://docs.python.org/3/whatsnew/3.5.html#heapq>`_                                                              |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | Element comparison in *merge()* can now be customized by passing a key function in a new optional key     |               |
-   | keyword argument, and a new optional *reverse* keyword argument can be used to reverse element comparison |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | `io <https://docs.python.org/3/whatsnew/3.5.html#io>`_                                                                    |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | A new *BufferedIOBase.readinto1()* method, that uses at most one call to the underlying raw stream's      |               |
-   | *RawIOBase.read()* or *RawIOBase.readinto()* methods                                                      |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | `json <https://docs.python.org/3/whatsnew/3.5.html#json>`_                                                |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | JSON decoder now raises JSONDecodeError instead of ValueError to provide better context information about |               |
-   | the error.                                                                                                |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | `math <https://docs.python.org/3/whatsnew/3.5.html#math>`_                                                                |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | Two new constants have been added to the math module: *inf* and *nan*.                                    |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | A new function *isclose()* provides a way to test for approximate equality.                               |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | A new *gcd()* function has been added. The *fractions.gcd()* function is now deprecated.                  |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | `os <https://docs.python.org/3/whatsnew/3.5.html#os>`_                                                                    |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | The new *scandir()* function returning an iterator of DirEntry objects has been added.                    |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | The *urandom()* function now uses the *getrandom()* syscall on Linux 3.17 or newer, and *getentropy()* on |               |
-   | OpenBSD 5.6 and newer, removing the need to use /dev/urandom and avoiding failures due to potential file  |               |
-   | descriptor exhaustion.                                                                                    |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | New *get_blocking()* and *set_blocking()* functions allow getting and setting a file descriptor's blocking|               |
-   | mode (O_NONBLOCK.)                                                                                        |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | There is a new *os.path.commonpath()* function returning the longest common sub-path of each passed       |               |
-   | pathname                                                                                                  |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | `re <https://docs.python.org/3/whatsnew/3.5.html#re>`_                                                    |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | References and conditional references to groups with fixed length are now allowed in lookbehind assertions|               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | The number of capturing groups in regular expressions is no longer limited to 100.                        |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | The *sub()* and *subn()* functions now replace unmatched groups with empty strings instead of raising an  |               |
-   | exception.                                                                                                |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | The *re.error* exceptions have new attributes, msg, pattern, pos, lineno, and colno, that provide better  |               |
-   | context information about the error                                                                       |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | `socket <https://docs.python.org/3/whatsnew/3.5.html#socket>`_                                                            |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | Functions with timeouts now use a monotonic clock, instead of a system clock.                             |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | A new *socket.sendfile()* method allows sending a file over a socket by using the high-performance        |               |
-   | *os.sendfile()* function on UNIX, resulting in uploads being from 2 to 3 times faster than when using     |               |
-   | plain *socket.send()*                                                                                     |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | The *socket.sendall()* method no longer resets the socket timeout every time bytes are received or sent.  |               |
-   | The socket timeout is now the maximum total duration to send all data.                                    |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | The backlog argument of the *socket.listen()* method is now optional. By default it is set to SOMAXCONN or|               |
-   | to 128, whichever is less.                                                                                |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | `ssl <https://docs.python.org/3/whatsnew/3.5.html#ssl>`_                                                                  |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | Memory BIO Support                                                                                        |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | Application-Layer Protocol Negotiation Support                                                            |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | There is a new *SSLSocket.version()* method to query the actual protocol version in use.                  |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | The SSLSocket class now implements a *SSLSocket.sendfile()* method.                                       |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | The *SSLSocket.send()* method now raises either the *ssl.SSLWantReadError* or *ssl.SSLWantWriteError*     |               |
-   | exception on a non-blocking socket if the operation would block. Previously, it would return 0.           |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | The *cert_time_to_seconds()* function now interprets the input time as UTC and not as local time, per RFC |               |
-   | 5280. Additionally, the return value is always an int.                                                    |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | New *SSLObject.shared_ciphers()* and *SSLSocket.shared_ciphers()* methods return the list of ciphers sent |               |
-   | by the client during the handshake.                                                                       |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | The *SSLSocket.do_handshake()*, *SSLSocket.read()*, *SSLSocket.shutdown()*, and *SSLSocket.write()*       |               |
-   | methods of the SSLSocket class no longer reset the socket timeout every time bytes are received or sent.  |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | The *match_hostname()* function now supports matching of IP addresses.                                    |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | `sys <https://docs.python.org/3/whatsnew/3.5.html#sys>`_                                                                  |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | A new *set_coroutine_wrapper()* function allows setting a global hook that will be called whenever a      |               |
-   | coroutine object is created by an async def function. A corresponding *get_coroutine_wrapper()* can be    |               |
-   | used to obtain a currently set wrapper.                                                                   |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | A new *is_finalizing()* function can be used to check if the Python interpreter is shutting down.         |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | `time <https://docs.python.org/3/whatsnew/3.5.html#time>`_                                                                |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
-   | The *monotonic()* function is now always available                                                        |               |
-   +-----------------------------------------------------------------------------------------------------------+---------------+
+.. table::
+  :widths: 90 10
+
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | `collections <https://docs.python.org/3/whatsnew/3.5.html#collections>`_                                                  |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The *OrderedDict* class is now implemented in C, which makes it 4 to 100 times faster.                    |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | *OrderedDict.items()* , *OrderedDict.keys()* , *OrderedDict.values()* views now support reversed()        |               |
+  | iteration.                                                                                                |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The deque class now defines *index()*, *insert()*, and *copy()*, and supports the + and * operators.      |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | Docstrings produced by namedtuple() can now be updated.                                                   |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The UserString class now implements the *__getnewargs__()*, *__rmod__()*, *casefold()*, *format_map()*,   |               |
+  | *isprintable()*, and *maketrans()* methods to match the corresponding methods of str.                     |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | `heapq <https://docs.python.org/3/whatsnew/3.5.html#heapq>`_                                                              |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | Element comparison in *merge()* can now be customized by passing a key function in a new optional key     |               |
+  | keyword argument, and a new optional *reverse* keyword argument can be used to reverse element comparison |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | `io <https://docs.python.org/3/whatsnew/3.5.html#io>`_                                                                    |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | A new *BufferedIOBase.readinto1()* method, that uses at most one call to the underlying raw stream's      |               |
+  | *RawIOBase.read()* or *RawIOBase.readinto()* methods                                                      |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | `json <https://docs.python.org/3/whatsnew/3.5.html#json>`_                                                |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | JSON decoder now raises JSONDecodeError instead of ValueError to provide better context information about |               |
+  | the error.                                                                                                |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | `math <https://docs.python.org/3/whatsnew/3.5.html#math>`_                                                                |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | Two new constants have been added to the math module: *inf* and *nan*.                                    | Complete      |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | A new function *isclose()* provides a way to test for approximate equality.                               |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | A new *gcd()* function has been added. The *fractions.gcd()* function is now deprecated.                  |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | `os <https://docs.python.org/3/whatsnew/3.5.html#os>`_                                                                    |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The new *scandir()* function returning an iterator of DirEntry objects has been added.                    |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The *urandom()* function now uses the *getrandom()* syscall on Linux 3.17 or newer, and *getentropy()* on |               |
+  | OpenBSD 5.6 and newer, removing the need to use /dev/urandom and avoiding failures due to potential file  |               |
+  | descriptor exhaustion.                                                                                    |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | New *get_blocking()* and *set_blocking()* functions allow getting and setting a file descriptor's blocking|               |
+  | mode (O_NONBLOCK.)                                                                                        |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | There is a new *os.path.commonpath()* function returning the longest common sub-path of each passed       |               |
+  | pathname                                                                                                  |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | `re <https://docs.python.org/3/whatsnew/3.5.html#re>`_                                                    |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | References and conditional references to groups with fixed length are now allowed in lookbehind assertions|               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The number of capturing groups in regular expressions is no longer limited to 100.                        |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The *sub()* and *subn()* functions now replace unmatched groups with empty strings instead of raising an  |               |
+  | exception.                                                                                                |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The *re.error* exceptions have new attributes, msg, pattern, pos, lineno, and colno, that provide better  |               |
+  | context information about the error                                                                       |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | `socket <https://docs.python.org/3/whatsnew/3.5.html#socket>`_                                                            |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | Functions with timeouts now use a monotonic clock, instead of a system clock.                             |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | A new *socket.sendfile()* method allows sending a file over a socket by using the high-performance        |               |
+  | *os.sendfile()* function on UNIX, resulting in uploads being from 2 to 3 times faster than when using     |               |
+  | plain *socket.send()*                                                                                     |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The *socket.sendall()* method no longer resets the socket timeout every time bytes are received or sent.  |               |
+  | The socket timeout is now the maximum total duration to send all data.                                    |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The backlog argument of the *socket.listen()* method is now optional. By default it is set to SOMAXCONN or| Complete      |
+  | to 128, whichever is less.                                                                                |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | `ssl <https://docs.python.org/3/whatsnew/3.5.html#ssl>`_                                                                  |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | Memory BIO Support                                                                                        |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | Application-Layer Protocol Negotiation Support                                                            |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | There is a new *SSLSocket.version()* method to query the actual protocol version in use.                  |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The SSLSocket class now implements a *SSLSocket.sendfile()* method.                                       |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The *SSLSocket.send()* method now raises either the *ssl.SSLWantReadError* or *ssl.SSLWantWriteError*     |               |
+  | exception on a non-blocking socket if the operation would block. Previously, it would return 0.           |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The *cert_time_to_seconds()* function now interprets the input time as UTC and not as local time, per RFC |               |
+  | 5280. Additionally, the return value is always an int.                                                    |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | New *SSLObject.shared_ciphers()* and *SSLSocket.shared_ciphers()* methods return the list of ciphers sent |               |
+  | by the client during the handshake.                                                                       |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The *SSLSocket.do_handshake()*, *SSLSocket.read()*, *SSLSocket.shutdown()*, and *SSLSocket.write()*       |               |
+  | methods of the SSLSocket class no longer reset the socket timeout every time bytes are received or sent.  |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The *match_hostname()* function now supports matching of IP addresses.                                    |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | `sys <https://docs.python.org/3/whatsnew/3.5.html#sys>`_                                                                  |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | A new *set_coroutine_wrapper()* function allows setting a global hook that will be called whenever a      |               |
+  | coroutine object is created by an async def function. A corresponding *get_coroutine_wrapper()* can be    |               |
+  | used to obtain a currently set wrapper.                                                                   |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | A new *is_finalizing()* function can be used to check if the Python interpreter is shutting down.         |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | `time <https://docs.python.org/3/whatsnew/3.5.html#time>`_                                                                |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The *monotonic()* function is now always available                                                        |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+
+.. rubric:: Notes
+
+.. [#fth] The MicroPython parser correct ignores all type hints. However, the ``typing`` module is not built-in.

docs/differences/python_36.rst

@@ -5,53 +5,59 @@ Python 3.6
 
 Python 3.6 beta 1 was released on 12 Sep 2016, and a summary of the new features can be found here:
 
-  +-----------------------------------------------------------------------------------------------------------+--------------+
-  | **New Syntax Features:**                                                                                  | **Status**   |
-  +--------------------------------------------------------+--------------------------------------------------+--------------+
-  | `PEP 498 <https://www.python.org/dev/peps/pep-0498/>`_ | Literal String Formatting                        |              |
-  +--------------------------------------------------------+--------------------------------------------------+--------------+
-  | `PEP 515 <https://www.python.org/dev/peps/pep-0515/>`_ | Underscores in Numeric Literals                  |              |
-  +--------------------------------------------------------+--------------------------------------------------+--------------+
-  | `PEP 525 <https://www.python.org/dev/peps/pep-0525/>`_ | Asynchronous Generators                          |              |
-  +--------------------------------------------------------+--------------------------------------------------+--------------+
-  | `PEP 526 <https://www.python.org/dev/peps/pep-0526/>`_ | Syntax for Variable Annotations (provisional)    |              |
-  +--------------------------------------------------------+--------------------------------------------------+--------------+
-  | `PEP 530 <https://www.python.org/dev/peps/pep-0530/>`_ | Asynchronous Comprehensions                      |              |
-  +--------------------------------------------------------+--------------------------------------------------+--------------+
-  | **New Built-in Features:**                                                                                               |
-  +--------------------------------------------------------+--------------------------------------------------+--------------+
-  | `PEP 468 <https://www.python.org/dev/peps/pep-0468/>`_ | Preserving the order of *kwargs* in a function   |              |
-  +--------------------------------------------------------+--------------------------------------------------+--------------+
-  | `PEP 487 <https://www.python.org/dev/peps/pep-0487/>`_ | Simpler customization of class creation          |              |
-  +--------------------------------------------------------+--------------------------------------------------+--------------+
-  | `PEP 520 <https://www.python.org/dev/peps/pep-0520/>`_ | Preserving Class Attribute Definition Order      |              |
-  +--------------------------------------------------------+--------------------------------------------------+--------------+
-  | **Standard Library Changes:**                                                                                            |
-  +--------------------------------------------------------+--------------------------------------------------+--------------+
-  | `PEP 495 <https://www.python.org/dev/peps/pep-0495/>`_ | Local Time Disambiguation                        |              |
-  +--------------------------------------------------------+--------------------------------------------------+--------------+
-  | `PEP 506 <https://www.python.org/dev/peps/pep-0506/>`_ | Adding A Secrets Module To The Standard Library  |              |
-  +--------------------------------------------------------+--------------------------------------------------+--------------+
-  | `PEP 519 <https://www.python.org/dev/peps/pep-0519/>`_ | Adding a file system path protocol               |              |
-  +--------------------------------------------------------+--------------------------------------------------+--------------+
-  | **CPython internals:**                                                                                                   |
-  +--------------------------------------------------------+--------------------------------------------------+--------------+
-  | `PEP 509 <https://www.python.org/dev/peps/pep-0509/>`_ | Add a private version to dict                    |              |
-  +--------------------------------------------------------+--------------------------------------------------+--------------+
-  | `PEP 523 <https://www.python.org/dev/peps/pep-0523/>`_ | Adding a frame evaluation API to CPython         |              |
-  +--------------------------------------------------------+--------------------------------------------------+--------------+
-  | **Linux/Window Changes**                                                                                                 |
-  +--------------------------------------------------------+--------------------------------------------------+--------------+
-  | `PEP 524 <https://www.python.org/dev/peps/pep-0524/>`_ | Make os.urandom() blocking on Linux              |              |
-  |                                                        | (during system startup)                          |              |
-  +--------------------------------------------------------+--------------------------------------------------+--------------+
-  | `PEP 528 <https://www.python.org/dev/peps/pep-0528/>`_ | Change Windows console encoding to UTF-8         |              |
-  +--------------------------------------------------------+--------------------------------------------------+--------------+
-  | `PEP 529 <https://www.python.org/dev/peps/pep-0529/>`_ | Change Windows filesystem encoding to UTF-8      |              |
-  +--------------------------------------------------------+--------------------------------------------------+--------------+
+.. table::
+  :widths: 30 50 20
+
+  +-----------------------------------------------------------------------------------------------------------+-----------------+
+  | **New Syntax Features**                                                                                   | **Status**      |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 498 <https://www.python.org/dev/peps/pep-0498/>`_ | Literal String Formatting                        | Complete        |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 515 <https://www.python.org/dev/peps/pep-0515/>`_ | Underscores in Numeric Literals                  | Complete        |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 525 <https://www.python.org/dev/peps/pep-0525/>`_ | Asynchronous Generators                          |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 526 <https://www.python.org/dev/peps/pep-0526/>`_ | Syntax for Variable Annotations (provisional)    | Complete        |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 530 <https://www.python.org/dev/peps/pep-0530/>`_ | Asynchronous Comprehensions                      |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | **New Built-in Features**                                                                                                   |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 468 <https://www.python.org/dev/peps/pep-0468/>`_ | Preserving the order of *kwargs* in a function   |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 487 <https://www.python.org/dev/peps/pep-0487/>`_ | Simpler customization of class creation          |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 520 <https://www.python.org/dev/peps/pep-0520/>`_ | Preserving Class Attribute Definition Order      |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | **Standard Library Changes**                                                                                                |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 495 <https://www.python.org/dev/peps/pep-0495/>`_ | Local Time Disambiguation                        |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 506 <https://www.python.org/dev/peps/pep-0506/>`_ | Adding A Secrets Module To The Standard Library  |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 519 <https://www.python.org/dev/peps/pep-0519/>`_ | Adding a file system path protocol               |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | **CPython Internals**                                                                                                       |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 509 <https://www.python.org/dev/peps/pep-0509/>`_ | Add a private version to dict                    | Won't do        |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 523 <https://www.python.org/dev/peps/pep-0523/>`_ | Adding a frame evaluation API to CPython         |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | **Linux/Window Changes**                                                                                                    |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 524 <https://www.python.org/dev/peps/pep-0524/>`_ | Make ``os.urandom()`` blocking on Linux          |                 |
+  |                                                        | (during system startup)                          |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 528 <https://www.python.org/dev/peps/pep-0528/>`_ | Change Windows console encoding to UTF-8         |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 529 <https://www.python.org/dev/peps/pep-0529/>`_ | Change Windows filesystem encoding to UTF-8      |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
 
 Other Language Changes:
 
+.. table::
+  :widths: 90 10
+
   +-------------------------------------------------------------------------------------------------------------+---------------+
   | A *global* or *nonlocal* statement must now textually appear before the first use of the affected name in   |               |
   | the same scope. Previously this was a SyntaxWarning.                                                        |               |
@@ -71,6 +77,9 @@ Other Language Changes:
 
 Changes to built-in modules:
 
+.. table::
+  :widths: 90 10
+
   +--------------------------------------------------------------------------------------------------------------+----------------+
   | `array <https://docs.python.org/3.6/whatsnew/3.6.html#array>`_                                               |                |
   +--------------------------------------------------------------------------------------------------------------+----------------+
@@ -78,7 +87,7 @@ Changes to built-in modules:
   +--------------------------------------------------------------------------------------------------------------+----------------+
   | `binascii <https://docs.python.org/3.6/whatsnew/3.6.html#binascii>`_                                         |                |
   +--------------------------------------------------------------------------------------------------------------+----------------+
-  | The b2a_base64() function now accepts an optional newline keyword argument to control whether the newline    |                |
+  | The b2a_base64() function now accepts an optional newline keyword argument to control whether the newline    | Complete       |
   | character is appended to the return value                                                                    |                |
   +--------------------------------------------------------------------------------------------------------------+----------------+
   | `cmath <https://docs.python.org/3.6/whatsnew/3.6.html#cmath>`_                                               |                |
@@ -121,7 +130,7 @@ Changes to built-in modules:
   +--------------------------------------------------------------------------------------------------------------+----------------+
   | `math <https://docs.python.org/3.6/whatsnew/3.6.html#math>`_                                                                  |
   +--------------------------------------------------------------------------------------------------------------+----------------+
-  | The new math.tau (τ) constant has been added                                                                 |                |
+  | The new math.tau (τ) constant has been added                                                                 | Complete       |
   +--------------------------------------------------------------------------------------------------------------+----------------+
   | `os <https://docs.python.org/3.6/whatsnew/3.6.html#os>`_                                                                      |
   +--------------------------------------------------------------------------------------------------------------+----------------+
@@ -136,7 +145,7 @@ Changes to built-in modules:
   | `re <https://docs.python.org/3.6/whatsnew/3.6.html#re>`_                                                                      |
   +--------------------------------------------------------------------------------------------------------------+----------------+
   | Added support of modifier spans in regular expressions. Examples: *'(?i:p)ython'* matches 'python' and       |                |
-  | 'Python', but not 'PYTHON'; *'(?i)g(?-i:v)r'* matches *'GvR'* and *'gvr'*, but not *'GVR'* .                 |                |
+  | 'Python', but not 'PYTHON'; *'(?i)g(?-i:v)r'* matches *'GvR'* and *'gvr'*, but not *'GVR'*.                  |                |
   +--------------------------------------------------------------------------------------------------------------+----------------+
   | Match object groups can be accessed by *__getitem__*, which is equivalent to *group()*. So *mo['name']* is   |                |
   | now equivalent to *mo.group('name')*.                                                                        |                |

docs/differences/python_37.rst

@@ -5,72 +5,81 @@ Python 3.7
 
 New Features:
 
-  +--------------------------------------------------------+--------------------------------------------------+----------------+
-  | **Features:**                                                                                             | **Status**     |
-  +--------------------------------------------------------+--------------------------------------------------+----------------+
-  | `PEP 538 <https://www.python.org/dev/peps/pep-0538/>`_ | Coercing the legacy C locale to a UTF-8 based    |                |
-  |                                                        | locale                                           |                |
-  +--------------------------------------------------------+--------------------------------------------------+----------------+
-  | `PEP 539 <https://www.python.org/dev/peps/pep-0539/>`_ | A New C-API for Thread-Local Storage in CPython  |                |
-  +--------------------------------------------------------+--------------------------------------------------+----------------+
-  | `PEP 540 <https://www.python.org/dev/peps/pep-0540/>`_ | UTF-8 mode                                       |                |
-  +--------------------------------------------------------+--------------------------------------------------+----------------+
-  | `PEP 552 <https://www.python.org/dev/peps/pep-0552/>`_ | Deterministic pyc                                |                |
-  +--------------------------------------------------------+--------------------------------------------------+----------------+
-  | `PEP 553 <https://www.python.org/dev/peps/pep-0553/>`_ | Built-in breakpoint()                            |                |
-  +--------------------------------------------------------+--------------------------------------------------+----------------+
-  | `PEP 557 <https://www.python.org/dev/peps/pep-0557/>`_ | Data Classes                                     |                |
-  +--------------------------------------------------------+--------------------------------------------------+----------------+
-  | `PEP 560 <https://www.python.org/dev/peps/pep-0560/>`_ | Core support for typing module and generic types |                |
-  +--------------------------------------------------------+--------------------------------------------------+----------------+
-  | `PEP 562 <https://www.python.org/dev/peps/pep-0562/>`_ | Module __getattr__ and __dir__                   | Partially done |
-  +--------------------------------------------------------+--------------------------------------------------+----------------+
-  | `PEP 563 <https://www.python.org/dev/peps/pep-0563/>`_ | Postponed Evaluation of Annotations              |                |
-  +--------------------------------------------------------+--------------------------------------------------+----------------+
-  | `PEP 564 <https://www.python.org/dev/peps/pep-0564/>`_ | Time functions with nanosecond resolution        |                |
-  +--------------------------------------------------------+--------------------------------------------------+----------------+
-  | `PEP 565 <https://www.python.org/dev/peps/pep-0565/>`_ | Show DeprecationWarning in __main__              |                |
-  +--------------------------------------------------------+--------------------------------------------------+----------------+
-  | `PEP 567 <https://www.python.org/dev/peps/pep-0567/>`_ | Context Variables                                |                |
-  +--------------------------------------------------------+--------------------------------------------------+----------------+
+.. table::
+  :widths: 20 60 20
+
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | **Feature**                                                                                               | **Status**                           |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 538 <https://www.python.org/dev/peps/pep-0538/>`_ | Coercing the legacy C locale to a UTF-8 based    |                                      |
+  |                                                        | locale                                           |                                      |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 539 <https://www.python.org/dev/peps/pep-0539/>`_ | A New C-API for Thread-Local Storage in CPython  |                                      |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 540 <https://www.python.org/dev/peps/pep-0540/>`_ | UTF-8 mode                                       |                                      |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 552 <https://www.python.org/dev/peps/pep-0552/>`_ | Deterministic pyc                                |                                      |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 553 <https://www.python.org/dev/peps/pep-0553/>`_ | Built-in ``breakpoint()``                        |                                      |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 557 <https://www.python.org/dev/peps/pep-0557/>`_ | Data Classes                                     |                                      |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 560 <https://www.python.org/dev/peps/pep-0560/>`_ | Core support for typing module and generic types |                                      |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 562 <https://www.python.org/dev/peps/pep-0562/>`_ | Module ``__getattr__`` and ``__dir__``           | Partial                              |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 563 <https://www.python.org/dev/peps/pep-0563/>`_ | Postponed Evaluation of Annotations              |                                      |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 564 <https://www.python.org/dev/peps/pep-0564/>`_ | Time functions with nanosecond resolution        | Partial [#ftimenanosec]_             |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 565 <https://www.python.org/dev/peps/pep-0565/>`_ | Show DeprecationWarning in ``__main__``          |                                      |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 567 <https://www.python.org/dev/peps/pep-0567/>`_ | Context Variables                                |                                      |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
 
 Other Language Changes:
 
-  +----------------------------------------------------------------------------------------------------------+----------------+
-  | async and await are now reserved keywords                                                                | Completed      |
-  +----------------------------------------------------------------------------------------------------------+----------------+
-  | dict objects must preserve insertion-order                                                               |                |
-  +----------------------------------------------------------------------------------------------------------+----------------+
-  | More than 255 arguments can now be passed to a function; a function can now have more than 255 parameters|                |
-  +----------------------------------------------------------------------------------------------------------+----------------+
-  | bytes.fromhex() and bytearray.fromhex() now ignore all ASCII whitespace, not only spaces                 |                |
-  +----------------------------------------------------------------------------------------------------------+----------------+
-  | str, bytes, and bytearray gained support for the new isascii() method, which can be used to test if a    |                |
-  | string or bytes contain only the ASCII characters                                                        |                |
-  +----------------------------------------------------------------------------------------------------------+----------------+
-  | ImportError now displays module name and module __file__ path whenfrom ... import ... fails              |                |
-  +----------------------------------------------------------------------------------------------------------+----------------+
-  | Circular imports involving absolute imports with binding a submodule to a name are now supported         |                |
-  +----------------------------------------------------------------------------------------------------------+----------------+
-  | object.__format__(x, '') is now equivalent to str(x) rather than format(str(self), '')                   |                |
-  +----------------------------------------------------------------------------------------------------------+----------------+
-  | In order to better support dynamic creation of stack traces, types.TracebackType can now be instantiated |                |
-  | from Python code, and the tb_next attribute on tracebacks is now writable                                |                |
-  +----------------------------------------------------------------------------------------------------------+----------------+
-  | When using the -m switch, sys.path[0] is now eagerly expanded to the full starting directory path, rather|                |
-  | than being left as the empty directory (which allows imports from the current working directory at the   |                |
-  | time when an import occurs)                                                                              |                |
-  +----------------------------------------------------------------------------------------------------------+----------------+
-  | The new -X importtime option or the PYTHONPROFILEIMPORTTIME environment variable can be used to show the |                |
-  | timing of each module import                                                                             |                |
-  +----------------------------------------------------------------------------------------------------------+----------------+
+.. table::
+  :widths: 90 10
+
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+  | ``async`` and ``await`` are now reserved keywords                                                               | Complete       |
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+  | ``dict`` objects must preserve insertion-order                                                                  |                |
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+  | More than 255 arguments can now be passed to a function; a function can now have more than 255 parameters       |                |
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+  | ``bytes.fromhex()`` and ``bytearray.fromhex()`` now ignore all ASCII whitespace, not only spaces                |                |
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+  | ``str``, ``bytes``, and ``bytearray`` gained support for the new ``isascii()`` method, which can be used to     |                |
+  | test if a string or bytes contain only the ASCII characters                                                     |                |
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+  | ``ImportError`` now displays module name and module ``__file__`` path when ``from ... import ...`` fails        |                |
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+  | Circular imports involving absolute imports with binding a submodule to a name are now supported                |                |
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+  | ``object.__format__(x, '')`` is now equivalent to ``str(x)`` rather than ``format(str(self), '')``              |                |
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+  | In order to better support dynamic creation of stack traces, ``types.TracebackType`` can now be                 |                |
+  | instantiated from Python code, and the ``tb_next`` attribute on tracebacks is now writable                      |                |
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+  | When using the ``-m`` switch, ``sys.path[0]`` is now eagerly expanded to the full starting directory path,      |                |
+  | rather than being left as the empty directory (which allows imports from the current working directory          |                |
+  | at the time when an import occurs)                                                                              |                |
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+  | The new ``-X importtime`` option or the ``PYTHONPROFILEIMPORTTIME`` environment variable can be used to         |                |
+  | show the timing of each module import                                                                           |                |
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
 
 Changes to built-in modules:
 
+.. table::
+  :widths: 90 10
+
   +------------------------------------------------------------------------------------------------------------+----------------+
   | `asyncio <https://docs.python.org/3/whatsnew/3.7.html#asyncio>`_                                           |                |
   +------------------------------------------------------------------------------------------------------------+----------------+
-  | asyncio (many, may need a separate ticket)                                                                 |                |
+  | Too many to list                                                                                           |                |
   +------------------------------------------------------------------------------------------------------------+----------------+
   | `gc <https://docs.python.org/3/whatsnew/3.7.html#gc>`_                                                     |                |
   +------------------------------------------------------------------------------------------------------------+----------------+
@@ -93,3 +102,7 @@ Changes to built-in modules:
   +------------------------------------------------------------------------------------------------------------+----------------+
   | Mostly updates to support nanosecond resolution in PEP564, see above                                       |                |
   +------------------------------------------------------------------------------------------------------------+----------------+
+
+.. rubric:: Notes
+
+.. [#ftimenanosec] Only :func:`time.time_ns` is implemented. 

docs/differences/python_38.rst

@@ -5,15 +5,18 @@ Python 3.8
 
 Python 3.8.0 (final) was released on the 14 October 2019. The Features for 3.8
 are defined in `PEP 569 <https://www.python.org/dev/peps/pep-0569/#id9>`_ and
-a detailed description of the changes can be found in What's New in `Python
+a detailed description of the changes can be found in `What's New in Python
 3.8. <https://docs.python.org/3/whatsnew/3.8.html>`_
 
+.. table::
+  :widths: 20 60 20
+
   +--------------------------------------------------------+---------------------------------------------------+---------------+
-  | **Features:**                                                                                              | Status        |
+  | **Features**                                                                                               | **Status**    |
   +--------------------------------------------------------+---------------------------------------------------+---------------+
   | `PEP 570 <https://www.python.org/dev/peps/pep-0570/>`_ | Positional-only arguments                         |               |
   +--------------------------------------------------------+---------------------------------------------------+---------------+
-  | `PEP 572 <https://www.python.org/dev/peps/pep-0572/>`_ | Assignment Expressions                            |               |
+  | `PEP 572 <https://www.python.org/dev/peps/pep-0572/>`_ | Assignment Expressions                            | Complete      |
   +--------------------------------------------------------+---------------------------------------------------+---------------+
   | `PEP 574 <https://www.python.org/dev/peps/pep-0574/>`_ | Pickle protocol 5 with out-of-band data           |               |
   +--------------------------------------------------------+---------------------------------------------------+---------------+
@@ -25,13 +28,16 @@ a detailed description of the changes can be found in What's New in `Python
   +--------------------------------------------------------+---------------------------------------------------+---------------+
   | **Miscellaneous**                                                                                                          |
   +------------------------------------------------------------------------------------------------------------+---------------+
-  |  f-strings support = for self-documenting expressions and debugging                                        | Completed     |
+  |  f-strings support = for self-documenting expressions and debugging                                        | Complete      |
   +------------------------------------------------------------------------------------------------------------+---------------+
 
 Other Language Changes:
 
+.. table::
+  :widths: 90 10
+
   +------------------------------------------------------------------------------------------------------------+-------------+
-  | A *continue* statement was illegal in the *finally* clause due to a problem with the implementation. In    | Completed   |
+  | A *continue* statement was illegal in the *finally* clause due to a problem with the implementation. In    | Complete    |
   | Python 3.8 this restriction was lifted                                                                     |             |
   +------------------------------------------------------------------------------------------------------------+-------------+
   | The *bool*, *int* , and *fractions.Fraction* types now have an *as_integer_ratio()* method like that found |             |
@@ -72,14 +78,17 @@ Other Language Changes:
 
 Changes to built-in modules:
 
+.. table::
+  :widths: 90 10
+
   +------------------------------------------------------------------------------------------------------------+-------------+
-  | `asyncio`                                                                                                                |
+  | `asyncio <https://docs.python.org/3/whatsnew/3.8.html#asyncio>`_                                                         |
   +------------------------------------------------------------------------------------------------------------+-------------+
-  | *asyncio.run()* has graduated from the provisional to stable API                                           | Completed   |
+  | *asyncio.run()* has graduated from the provisional to stable API                                           | Complete    |
   +------------------------------------------------------------------------------------------------------------+-------------+
   | Running *python -m asyncio* launches a natively async REPL                                                 |             |
   +------------------------------------------------------------------------------------------------------------+-------------+
-  | The exception *asyncio.CancelledError* now inherits from *BaseException* rather than *Exception* and no    | Completed   |
+  | The exception *asyncio.CancelledError* now inherits from *BaseException* rather than *Exception* and no    | Complete    |
   | longer inherits from *concurrent.futures.CancelledError*                                                   |             |
   +------------------------------------------------------------------------------------------------------------+-------------+
   | Added *asyncio.Task.get_coro()* for getting the wrapped coroutine within an *asyncio.Task*                 |             |
@@ -90,12 +99,12 @@ Changes to built-in modules:
   | Added support for Happy Eyeballs to *asyncio.loop.create_connection()*. To specify the behavior, two new   |             |
   | parameters have been added: *happy_eyeballs_delay* and interleave.                                         |             |
   +------------------------------------------------------------------------------------------------------------+-------------+
-  | `gc`                                                                                                                     |
+  | `gc <https://docs.python.org/3/whatsnew/3.8.html#gc>`_                                                                   |
   +------------------------------------------------------------------------------------------------------------+-------------+
   | *get_objects()* can now receive an optional generation parameter indicating a generation to get objects    |             |
   | from. (Note, though, that while *gc* is a built-in, *get_objects()* is not implemented for MicroPython)    |             |
   +------------------------------------------------------------------------------------------------------------+-------------+
-  | `math`                                                                                                                   |
+  | `math <https://docs.python.org/3/whatsnew/3.8.html#math>`_                                                               |
   +------------------------------------------------------------------------------------------------------------+-------------+
   | Added new function *math.dist()* for computing Euclidean distance between two points                       |             |
   +------------------------------------------------------------------------------------------------------------+-------------+
@@ -109,9 +118,9 @@ Changes to built-in modules:
   | Added a new function *math.isqrt()* for computing accurate integer square roots without conversion to      |             |
   | floating point                                                                                             |             |
   +------------------------------------------------------------------------------------------------------------+-------------+
-  | The function *math.factorial()* no longer accepts arguments that are not int-like                          | Completed   |
+  | The function *math.factorial()* no longer accepts arguments that are not int-like                          | Complete    |
   +------------------------------------------------------------------------------------------------------------+-------------+
-  | `sys`                                                                                                                    |
+  | `sys <https://docs.python.org/3/whatsnew/3.8.html#sys>`_                                                                 |
   +------------------------------------------------------------------------------------------------------------+-------------+
   | Add new *sys.unraisablehook()* function which can be overridden to control how "unraisable exceptions"     |             |
   | are handled                                                                                                |             |

docs/differences/python_39.rst

@@ -8,35 +8,41 @@ defined in `PEP 596 <https://www.python.org/dev/peps/pep-0596/#features-for-3-9>
 and a detailed description of the changes can be found in
 `What's New in Python 3.9 <https://docs.python.org/3/whatsnew/3.9.html>`_
 
-  +--------------------------------------------------------+----------------------------------------------------+--------------+
-  | **Features:**                                          |                                                    | **Status**   |
-  +--------------------------------------------------------+----------------------------------------------------+--------------+
-  | `PEP 573 <https://www.python.org/dev/peps/pep-0573/>`_ | fast access to module state from methods of C      |              |
-  |                                                        | extension types                                    |              |
-  +--------------------------------------------------------+----------------------------------------------------+--------------+
-  | `PEP 584 <https://www.python.org/dev/peps/pep-0584/>`_ | union operators added to dict                      |              |
-  +--------------------------------------------------------+----------------------------------------------------+--------------+
-  | `PEP 585 <https://www.python.org/dev/peps/pep-0584/>`_ | type hinting generics in standard collections      |              |
-  +--------------------------------------------------------+----------------------------------------------------+--------------+
-  | `PEP 593 <https://www.python.org/dev/peps/pep-0593/>`_ | flexible function and variable annotations         |              |
-  +--------------------------------------------------------+----------------------------------------------------+--------------+
-  | `PEP 602 <https://www.python.org/dev/peps/pep-0602/>`_ | CPython adopts an annual release cycle. Instead of |              |
-  |                                                        | annual, aiming for two month release cycle         |              |
-  +--------------------------------------------------------+----------------------------------------------------+--------------+
-  | `PEP 614 <https://www.python.org/dev/peps/pep-0614/>`_ | relaxed grammar restrictions on decorators         |              |
-  +--------------------------------------------------------+----------------------------------------------------+--------------+
-  | `PEP 615 <https://www.python.org/dev/peps/pep-0615/>`_ | the IANA Time Zone Database is now present in the  |              |
-  |                                                        | standard library in the zoneinfo module            |              |
-  +--------------------------------------------------------+----------------------------------------------------+--------------+
-  | `PEP 616 <https://www.python.org/dev/peps/pep-0616/>`_ | string methods to remove prefixes and suffixes     |              |
-  +--------------------------------------------------------+----------------------------------------------------+--------------+
-  | `PEP 617 <https://www.python.org/dev/peps/pep-0617/>`_ | CPython now uses a new parser based on PEG         |              |
-  +--------------------------------------------------------+----------------------------------------------------+--------------+
+.. table::
+  :widths: 20 60 20
+
+  +--------------------------------------------------------+----------------------------------------------------+----------------------+
+  | **Features**                                           |                                                    | **Status**           |
+  +--------------------------------------------------------+----------------------------------------------------+----------------------+
+  | `PEP 573 <https://www.python.org/dev/peps/pep-0573/>`_ | Fast access to module state from methods of C      | Not relevant         |
+  |                                                        | extension types                                    |                      |
+  +--------------------------------------------------------+----------------------------------------------------+----------------------+
+  | `PEP 584 <https://www.python.org/dev/peps/pep-0584/>`_ | Union operators added to dict                      | Complete [#pep584]_  |
+  +--------------------------------------------------------+----------------------------------------------------+----------------------+
+  | `PEP 585 <https://www.python.org/dev/peps/pep-0584/>`_ | Type hinting generics in standard collections      |                      |
+  +--------------------------------------------------------+----------------------------------------------------+----------------------+
+  | `PEP 593 <https://www.python.org/dev/peps/pep-0593/>`_ | Flexible function and variable annotations         |                      |
+  +--------------------------------------------------------+----------------------------------------------------+----------------------+
+  | `PEP 602 <https://www.python.org/dev/peps/pep-0602/>`_ | CPython adopts an annual release cycle. Instead of | Not relevant         |
+  |                                                        | annual, aiming for two month release cycle         |                      |
+  +--------------------------------------------------------+----------------------------------------------------+----------------------+
+  | `PEP 614 <https://www.python.org/dev/peps/pep-0614/>`_ | Relaxed grammar restrictions on decorators         |                      |
+  +--------------------------------------------------------+----------------------------------------------------+----------------------+
+  | `PEP 615 <https://www.python.org/dev/peps/pep-0615/>`_ | The IANA Time Zone Database is now present in the  |                      |
+  |                                                        | standard library in the zoneinfo module            |                      |
+  +--------------------------------------------------------+----------------------------------------------------+----------------------+
+  | `PEP 616 <https://www.python.org/dev/peps/pep-0616/>`_ | String methods to remove prefixes and suffixes     |                      |
+  +--------------------------------------------------------+----------------------------------------------------+----------------------+
+  | `PEP 617 <https://www.python.org/dev/peps/pep-0617/>`_ | CPython now uses a new parser based on PEG         | Not relevant         |
+  +--------------------------------------------------------+----------------------------------------------------+----------------------+
 
 Other Language Changes:
 
+.. table::
+  :widths: 90 10
+
   +-------------------------------------------------------------------------------------------------------------+---------------+
-  | *__import__()* now raises *ImportError* instead of *ValueError*                                             | Completed     |
+  | *__import__()* now raises *ImportError* instead of *ValueError*                                             | Complete      |
   +-------------------------------------------------------------------------------------------------------------+---------------+
   | Python now gets the absolute path of the script filename specified on the command line (ex: *python3*       |               |
   | *script.py*): the *__file__* attribute of the *__main__* module became an absolute path, rather than a      |               |
@@ -62,8 +68,11 @@ Other Language Changes:
 
 Changes to built-in modules:
 
+.. table::
+  :widths: 90 10
+
   +---------------------------------------------------------------------------------------------------------------+---------------+
-  | `asyncio`                                                                                                                     |
+  | `asyncio <https://docs.python.org/3/whatsnew/3.9.html#asyncio>`_                                                              |
   +---------------------------------------------------------------------------------------------------------------+---------------+
   | Due to significant security concerns, the reuse_address parameter of *asyncio.loop.create_datagram_endpoint()*|               |
   | is no longer supported                                                                                        |               |
@@ -82,13 +91,13 @@ Changes to built-in modules:
   +---------------------------------------------------------------------------------------------------------------+---------------+
   | *asyncio* now raises *TyperError* when calling incompatible methods with an *ssl.SSLSocket* socket            |               |
   +---------------------------------------------------------------------------------------------------------------+---------------+
-  | `gc`                                                                                                                          |
+  | `gc <https://docs.python.org/3/whatsnew/3.9.html#gc>`_                                                                        |
   +---------------------------------------------------------------------------------------------------------------+---------------+
   | Garbage collection does not block on resurrected objects                                                      |               |
   +---------------------------------------------------------------------------------------------------------------+---------------+
   | Added a new function *gc.is_finalized()* to check if an object has been finalized by the garbage collector    |               |
   +---------------------------------------------------------------------------------------------------------------+---------------+
-  | `math`                                                                                                                        |
+  | `math <https://docs.python.org/3/whatsnew/3.9.html#math>`_                                                                    |
   +---------------------------------------------------------------------------------------------------------------+---------------+
   | Expanded the *math.gcd()* function to handle multiple arguments. Formerly, it only supported two arguments    |               |
   +---------------------------------------------------------------------------------------------------------------+---------------+
@@ -98,24 +107,28 @@ Changes to built-in modules:
   +---------------------------------------------------------------------------------------------------------------+---------------+
   | Added *math.ulp()*: return the value of the least significant bit of a float                                  |               |
   +---------------------------------------------------------------------------------------------------------------+---------------+
-  | `os`                                                                                                                          |
+  | `os <https://docs.python.org/3/whatsnew/3.9.html#os>`_                                                                        |
   +---------------------------------------------------------------------------------------------------------------+---------------+
   | Exposed the Linux-specific *os.pidfd_open()* and *os.P_PIDFD*                                                 |               |
   +---------------------------------------------------------------------------------------------------------------+---------------+
-  | The *os.unsetenv()* function is now also available on Windows                                                 | Completed     |
+  | The *os.unsetenv()* function is now also available on Windows                                                 | Complete      |
   +---------------------------------------------------------------------------------------------------------------+---------------+
-  | The *os.putenv()* and *os.unsetenv()* functions are now always available                                      | Completed     |
+  | The *os.putenv()* and *os.unsetenv()* functions are now always available                                      | Complete      |
   +---------------------------------------------------------------------------------------------------------------+---------------+
   |  Added *os.waitstatus_to_exitcode()* function: convert a wait status to an exit code                          |               |
   +---------------------------------------------------------------------------------------------------------------+---------------+
-  | `random`                                                                                                                      |
+  | `random <https://docs.python.org/3/whatsnew/3.9.html#random>`_                                                                |
   +---------------------------------------------------------------------------------------------------------------+---------------+
   | Added a new *random.Random.randbytes* method: generate random bytes                                           |               |
   +---------------------------------------------------------------------------------------------------------------+---------------+
-  | `sys`                                                                                                                         |
+  | `sys <https://docs.python.org/3/whatsnew/3.9.html#sys>`_                                                                      |
   +---------------------------------------------------------------------------------------------------------------+---------------+
   | Added a new *sys.platlibdir* attribute: name of the platform-specific library directory                       |               |
   +---------------------------------------------------------------------------------------------------------------+---------------+
   | Previously, *sys.stderr* was block-buffered when non-interactive. Now stderr defaults to always being         |               |
   | line-buffered                                                                                                 |               |
   +---------------------------------------------------------------------------------------------------------------+---------------+
+
+.. rubric:: Notes
+
+.. [#pep584] PEP 584 ``dict`` union operator is only available on MicroPython builds with ``MICROPY_CPYTHON_COMPAT`` enabled.

docs/esp32/quickref.rst

@@ -68,6 +68,9 @@ by reading the temperature sensor immediately after waking up from sleep.
 Networking
 ----------
 
+WLAN
+^^^^
+
 The :mod:`network` module::
 
     import network
@@ -76,12 +79,12 @@ The :mod:`network` module::
     wlan.active(True)       # activate the interface
     wlan.scan()             # scan for access points
     wlan.isconnected()      # check if the station is connected to an AP
-    wlan.connect('essid', 'password') # connect to an AP
+    wlan.connect('ssid', 'key') # connect to an AP
     wlan.config('mac')      # get the interface's MAC address
     wlan.ifconfig()         # get the interface's IP/netmask/gw/DNS addresses
 
     ap = network.WLAN(network.AP_IF) # create access-point interface
-    ap.config(essid='ESP-AP') # set the ESSID of the access point
+    ap.config(ssid='ESP-AP') # set the SSID of the access point
     ap.config(max_clients=10) # set how many clients can connect to the network
     ap.active(True)         # activate the interface
 
@@ -93,7 +96,7 @@ A useful function for connecting to your local WiFi network is::
         wlan.active(True)
         if not wlan.isconnected():
             print('connecting to network...')
-            wlan.connect('essid', 'password')
+            wlan.connect('ssid', 'key')
             while not wlan.isconnected():
                 pass
         print('network config:', wlan.ifconfig())
@@ -110,6 +113,67 @@ calling ``wlan.config(reconnects=n)``, where n are the number of desired reconne
 attempts (0 means it won't retry, -1 will restore the default behaviour of trying
 to reconnect forever).
 
+LAN
+^^^
+
+To use the wired interfaces one has to specify the pins and mode ::
+
+    import network
+
+    lan = network.LAN(mdc=PIN_MDC, ...)   # Set the pin and mode configuration
+    lan.active(True)                      # activate the interface
+    lan.ifconfig()                        # get the interface's IP/netmask/gw/DNS addresses
+
+
+The keyword arguments for the constructor defining the PHY type and interface are:
+
+- mdc=pin-object    # set the mdc and mdio pins.
+- mdio=pin-object
+- power=pin-object  # set the pin which switches the power of the PHY device.
+- phy_type=<type>   # Select the PHY device type. Supported devices are PHY_LAN8710,
+  PHY_LAN8720, PH_IP101, PHY_RTL8201, PHY_DP83848 and PHY_KSZ8041
+- phy_addr=number   # The address number of the PHY device.
+- ref_clk_mode=mode # Defines, whether the ref_clk at the ESP32 is an input
+  or output. Suitable values are Pin.IN and Pin.OUT.
+- ref_clk=pin-object  # defines the Pin used for ref_clk.
+
+The options ref_clk_mode and ref_clk require at least esp-idf version 4.4. For
+earlier esp-idf versions, these parameters must be defined by kconfig board options.
+
+These are working configurations for LAN interfaces of popular boards::
+
+    # Olimex ESP32-GATEWAY: power controlled by Pin(5)
+    # Olimex ESP32 PoE and ESP32-PoE ISO: power controlled by Pin(12)
+
+    lan = network.LAN(mdc=machine.Pin(23), mdio=machine.Pin(18), power=machine.Pin(5),
+                      phy_type=network.PHY_LAN8720, phy_addr=0)
+
+    # or with dynamic ref_clk pin configuration
+
+    lan = network.LAN(mdc=machine.Pin(23), mdio=machine.Pin(18), power=machine.Pin(5), 
+                      phy_type=network.PHY_LAN8720, phy_addr=0,
+                      ref_clk=machine.Pin(17), ref_clk_mode=machine.Pin.OUT)
+
+    # Wireless-Tag's WT32-ETH01
+
+    lan = network.LAN(mdc=machine.Pin(23), mdio=machine.Pin(18),
+                      phy_type=network.PHY_LAN8720, phy_addr=1, power=None)
+
+    # Espressif ESP32-Ethernet-Kit_A_V1.2
+
+    lan = network.LAN(id=0, mdc=Pin(23), mdio=Pin(18), power=Pin(5),
+                      phy_type=network.PHY_IP101, phy_addr=1)
+
+A suitable definition of the PHY interface in a sdkconfig.board file is::
+
+    CONFIG_ETH_PHY_INTERFACE_RMII=y
+    CONFIG_ETH_RMII_CLK_OUTPUT=y
+    CONFIG_ETH_RMII_CLK_OUT_GPIO=17
+    CONFIG_LWIP_LOCAL_HOSTNAME="ESP32_POE"
+
+The value assigned to CONFIG_ETH_RMII_CLK_OUT_GPIO may vary depending on the
+board's wiring.
+
 Delay and timing
 ----------------
 
@@ -160,6 +224,7 @@ Use the :ref:`machine.Pin <machine.Pin>` class::
 
     p4 = Pin(4, Pin.IN, Pin.PULL_UP) # enable internal pull-up resistor
     p5 = Pin(5, Pin.OUT, value=1) # set pin high on creation
+    p6 = Pin(6, Pin.OUT, drive=Pin.DRIVE_3) # set maximum drive strength
 
 Available Pins are from the following ranges (inclusive): 0-19, 21-23, 25-27, 32-39.
 These correspond to the actual GPIO pin numbers of ESP32 chip.  Note that many
@@ -167,6 +232,23 @@ end-user boards use their own adhoc pin numbering (marked e.g. D0, D1, ...).
 For mapping between board logical pins and physical chip pins consult your board
 documentation.
 
+Four drive strengths are supported, using the ``drive`` keyword argument to the
+``Pin()`` constructor or ``Pin.init()`` method, with different corresponding
+safe maximum source/sink currents and approximate internal driver resistances:
+
+ - ``Pin.DRIVE_0``: 5mA / 130 ohm
+ - ``Pin.DRIVE_1``: 10mA / 60 ohm
+ - ``Pin.DRIVE_2``: 20mA / 30 ohm (default strength if not configured)
+ - ``Pin.DRIVE_3``: 40mA / 15 ohm
+
+The ``hold=`` keyword argument to ``Pin()`` and ``Pin.init()`` will enable the
+ESP32 "pad hold" feature. When set to ``True``, the pin configuration
+(direction, pull resistors and output value) will be held and any further
+changes (including changing the output level) will not be applied. Setting
+``hold=False`` will immediately apply any outstanding pin configuration changes
+and release the pin. Using ``hold=True`` while a pin is already held will apply
+any configuration changes and then immediately reapply the hold.
+
 Notes:
 
 * Pins 1 and 3 are REPL UART TX and RX respectively
@@ -176,8 +258,7 @@ Notes:
 
 * Pins 34-39 are input only, and also do not have internal pull-up resistors
 
-* The pull value of some pins can be set to ``Pin.PULL_HOLD`` to reduce power
-  consumption during deepsleep.
+* See :ref:`Deep_sleep_Mode` for a discussion of pin behaviour during sleep
 
 There's a higher-level abstraction :ref:`machine.Signal <machine.Signal>`
 which can be used to invert a pin. Useful for illuminating active-low LEDs
@@ -199,9 +280,10 @@ They each have default GPIO assigned to them, however depending on your
 ESP32 variant and board, these pins may conflict with embedded flash,
 onboard PSRAM or peripherals.
 
-Any GPIO can be used for hardware UARTs using the GPIO matrix, so to avoid
-conflicts simply provide ``tx`` and ``rx`` pins when constructing. The default
-pins listed below.
+Any GPIO can be used for hardware UARTs using the GPIO matrix, except for
+input-only pins 34-39 that can be used as ``rx``. To avoid conflicts simply
+provide ``tx`` and ``rx`` pins when constructing. The default pins listed
+below.
 
 =====  =====  =====  =====
 \      UART0  UART1  UART2
@@ -264,54 +346,99 @@ See more examples in the :ref:`esp32_pwm` tutorial.
 ADC (analog to digital conversion)
 ----------------------------------
 
-On the ESP32 ADC functionality is available on Pins 32-39. Note that, when
-using the default configuration, input voltages on the ADC pin must be between
-0.0v and 1.0v (anything above 1.0v will just read as 4095).  Attenuation must
-be applied in order to increase this usable voltage range.
+On the ESP32, ADC functionality is available on pins 32-39 (ADC block 1) and
+pins 0, 2, 4, 12-15 and 25-27 (ADC block 2).
 
 Use the :ref:`machine.ADC <machine.ADC>` class::
 
     from machine import ADC
 
-    adc = ADC(Pin(32))          # create ADC object on ADC pin
-    adc.read()                  # read value, 0-4095 across voltage range 0.0v - 1.0v
+    adc = ADC(pin)        # create an ADC object acting on a pin
+    val = adc.read_u16()  # read a raw analog value in the range 0-65535
+    val = adc.read_uv()   # read an analog value in microvolts
 
-    adc.atten(ADC.ATTN_11DB)    # set 11dB input attenuation (voltage range roughly 0.0v - 3.6v)
-    adc.width(ADC.WIDTH_9BIT)   # set 9 bit return values (returned range 0-511)
-    adc.read()                  # read value using the newly configured attenuation and width
+ADC block 2 is also used by WiFi and so attempting to read analog values from
+block 2 pins when WiFi is active will raise an exception.
 
-ESP32 specific ADC class method reference:
+The internal ADC reference voltage is typically 1.1V, but varies slightly from
+package to package. The ADC is less linear close to the reference voltage
+(particularly at higher attenuations) and has a minimum measurement voltage
+around 100mV, voltages at or below this will read as 0. To read voltages
+accurately, it is recommended to use the ``read_uv()`` method (see below).
 
-.. method:: ADC.atten(attenuation)
+ESP32-specific ADC class method reference:
 
-    This method allows for the setting of the amount of attenuation on the
-    input of the ADC. This allows for a wider possible input voltage range,
-    at the cost of accuracy (the same number of bits now represents a wider
-    range). The possible attenuation options are:
+.. class:: ADC(pin, *, atten)
 
-      - ``ADC.ATTN_0DB``: 0dB attenuation, gives a maximum input voltage
-        of 1.00v - this is the default configuration
-      - ``ADC.ATTN_2_5DB``: 2.5dB attenuation, gives a maximum input voltage
-        of approximately 1.34v
-      - ``ADC.ATTN_6DB``: 6dB attenuation, gives a maximum input voltage
-        of approximately 2.00v
-      - ``ADC.ATTN_11DB``: 11dB attenuation, gives a maximum input voltage
-        of approximately 3.6v
+    Return the ADC object for the specified pin. ESP32 does not support
+    different timings for ADC sampling and so the ``sample_ns`` keyword argument
+    is not supported.
+
+    To read voltages above the reference voltage, apply input attenuation with
+    the ``atten`` keyword argument. Valid values (and approximate linear
+    measurement ranges) are:
+
+      - ``ADC.ATTN_0DB``: No attenuation (100mV - 950mV)
+      - ``ADC.ATTN_2_5DB``: 2.5dB attenuation (100mV - 1250mV)
+      - ``ADC.ATTN_6DB``: 6dB attenuation (150mV - 1750mV)
+      - ``ADC.ATTN_11DB``: 11dB attenuation (150mV - 2450mV)
 
 .. Warning::
-   Despite 11dB attenuation allowing for up to a 3.6v range, note that the
-   absolute maximum voltage rating for the input pins is 3.6v, and so going
-   near this boundary may be damaging to the IC!
+   Note that the absolute maximum voltage rating for input pins is 3.6V. Going
+   near to this boundary risks damage to the IC!
 
-.. method:: ADC.width(width)
+.. method:: ADC.read_uv()
 
-    This method allows for the setting of the number of bits to be utilised
-    and returned during ADC reads. Possible width options are:
+    This method uses the known characteristics of the ADC and per-package eFuse
+    values - set during manufacture - to return a calibrated input voltage
+    (before attenuation) in microvolts. The returned value has only millivolt
+    resolution (i.e., will always be a multiple of 1000 microvolts).
+
+    The calibration is only valid across the linear range of the ADC. In
+    particular, an input tied to ground will read as a value above 0 microvolts.
+    Within the linear range, however, more accurate and consistent results will
+    be obtained than using `read_u16()` and scaling the result with a constant.
+
+The ESP32 port also supports the :ref:`machine.ADC <machine.ADCBlock>` API:
+
+.. class:: ADCBlock(id, *, bits)
+
+    Return the ADC block object with the given ``id`` (1 or 2) and initialize
+    it to the specified resolution (9 to 12-bits depending on the ESP32 series)
+    or the highest supported resolution if not specified.
+
+.. method:: ADCBlock.connect(pin)
+            ADCBlock.connect(channel)
+            ADCBlock.connect(channel, pin)
+
+    Return the ``ADC`` object for the specified ADC pin or channel number.
+    Arbitrary connection of ADC channels to GPIO is not supported and so
+    specifying a pin that is not connected to this block, or specifying a
+    mismatched channel and pin, will raise an exception.
+
+Legacy methods:
+
+.. method:: ADC.read()
+
+    This method returns the raw ADC value ranged according to the resolution of
+    the block, e.g., 0-4095 for 12-bit resolution.
+
+.. method:: ADC.atten(atten)
+
+    Equivalent to ``ADC.init(atten=atten)``.
+
+.. method:: ADC.width(bits)
+
+    Equivalent to ``ADC.block().init(bits=bits)``.
+
+For compatibility, the ``ADC`` object also provides constants matching the
+supported ADC resolutions:
+
+  - ``ADC.WIDTH_9BIT`` = 9
+  - ``ADC.WIDTH_10BIT`` = 10
+  - ``ADC.WIDTH_11BIT`` = 11
+  - ``ADC.WIDTH_12BIT`` = 12
 
-      - ``ADC.WIDTH_9BIT``: 9 bit data
-      - ``ADC.WIDTH_10BIT``: 10 bit data
-      - ``ADC.WIDTH_11BIT``: 11 bit data
-      - ``ADC.WIDTH_12BIT``: 12 bit data - this is the default configuration
 
 Software SPI bus
 ----------------
@@ -453,6 +580,8 @@ See :ref:`machine.WDT <machine.WDT>`. ::
     wdt = WDT(timeout=5000)
     wdt.feed()
 
+.. _Deep_sleep_mode:
+
 Deep-sleep mode
 ---------------
 
@@ -472,15 +601,49 @@ Notes:
 * Calling ``deepsleep()`` without an argument will put the device to sleep
   indefinitely
 * A software reset does not change the reset cause
-* There may be some leakage current flowing through enabled internal pullups.
-  To further reduce power consumption it is possible to disable the internal pullups::
 
-    p1 = Pin(4, Pin.IN, Pin.PULL_HOLD)
+Some ESP32 pins (0, 2, 4, 12-15, 25-27, 32-39) are connected to the RTC during
+deep-sleep and can be used to wake the device with the ``wake_on_`` functions in
+the :mod:`esp32` module. The output-capable RTC pins (all except 34-39) will
+also retain their pull-up or pull-down resistor configuration when entering
+deep-sleep.
 
-  After leaving deepsleep it may be necessary to un-hold the pin explicitly (e.g. if
-  it is an output pin) via::
+If the pull resistors are not actively required during deep-sleep and are likely
+to cause current leakage (for example a pull-up resistor is connected to ground
+through a switch), then they should be disabled to save power before entering
+deep-sleep mode::
 
-    p1 = Pin(4, Pin.OUT, None)
+    from machine import Pin, deepsleep
+
+    # configure input RTC pin with pull-up on boot
+    pin = Pin(2, Pin.IN, Pin.PULL_UP)
+
+    # disable pull-up and put the device to sleep for 10 seconds
+    pin.init(pull=None)
+    machine.deepsleep(10000)
+
+Output-configured RTC pins will also retain their output direction and level in
+deep-sleep if pad hold is enabled with the ``hold=True`` argument to
+``Pin.init()``.
+
+Non-RTC GPIO pins will be disconnected by default on entering deep-sleep.
+Configuration of non-RTC pins - including output level - can be retained by
+enabling pad hold on the pin and enabling GPIO pad hold during deep-sleep::
+
+    from machine import Pin, deepsleep
+    import esp32
+
+    opin = Pin(19, Pin.OUT, value=1, hold=True) # hold output level
+    ipin = Pin(21, Pin.IN, Pin.PULL_UP, hold=True) # hold pull-up
+
+    # enable pad hold in deep-sleep for non-RTC GPIO
+    esp32.gpio_deep_sleep_hold(True)
+
+    # put the device to sleep for 10 seconds
+    deepsleep(10000)
+
+The pin configuration - including the pad hold - will be retained on wake from
+sleep. See :ref:`Pins_and_GPIO` above for a further discussion of pad holding.
 
 SD card
 -------
@@ -491,7 +654,7 @@ See :ref:`machine.SDCard <machine.SDCard>`. ::
 
     # Slot 2 uses pins sck=18, cs=5, miso=19, mosi=23
     sd = machine.SDCard(slot=2)
-    os.mount(sd, "/sd")  # mount
+    os.mount(sd, '/sd')  # mount
 
     os.listdir('/sd')    # list directory contents
 
@@ -562,18 +725,14 @@ The APA106 driver extends NeoPixel, but internally uses a different colour order
     ap = APA106(pin, 8)
     r, g, b = ap[0]
 
-For low-level driving of a NeoPixel::
-
-    import esp
-    esp.neopixel_write(pin, grb_buf, is800khz)
-
 .. Warning::
    By default ``NeoPixel`` is configured to control the more popular *800kHz*
    units. It is possible to use alternative timing to control other (typically
    400kHz) devices by passing ``timing=0`` when constructing the
    ``NeoPixel`` object.
 
-The low-level driver uses an RMT channel by default.  To configure this see
+For low-level driving of a NeoPixel see `machine.bitstream`.
+This low-level driver uses an RMT channel by default.  To configure this see
 `RMT.bitstream_channel`.
 
 APA102 (DotStar) uses a different driver as it has an additional clock pin.

docs/esp8266/quickref.rst

@@ -57,13 +57,13 @@ The :mod:`network` module::
     wlan.active(True)       # activate the interface
     wlan.scan()             # scan for access points
     wlan.isconnected()      # check if the station is connected to an AP
-    wlan.connect('essid', 'password') # connect to an AP
+    wlan.connect('ssid', 'key') # connect to an AP
     wlan.config('mac')      # get the interface's MAC address
     wlan.ifconfig()         # get the interface's IP/netmask/gw/DNS addresses
 
     ap = network.WLAN(network.AP_IF) # create access-point interface
     ap.active(True)         # activate the interface
-    ap.config(essid='ESP-AP') # set the ESSID of the access point
+    ap.config(ssid='ESP-AP') # set the SSID of the access point
 
 A useful function for connecting to your local WiFi network is::
 
@@ -73,7 +73,7 @@ A useful function for connecting to your local WiFi network is::
         wlan.active(True)
         if not wlan.isconnected():
             print('connecting to network...')
-            wlan.connect('essid', 'password')
+            wlan.connect('ssid', 'key')
             while not wlan.isconnected():
                 pass
         print('network config:', wlan.ifconfig())
@@ -374,17 +374,13 @@ Use the ``neopixel`` module::
     np.write()              # write data to all pixels
     r, g, b = np[0]         # get first pixel colour
 
-For low-level driving of a NeoPixel::
-
-    import esp
-    esp.neopixel_write(pin, grb_buf, is800khz)
-
 .. Warning::
    By default ``NeoPixel`` is configured to control the more popular *800kHz*
    units. It is possible to use alternative timing to control other (typically
    400kHz) devices by passing ``timing=0`` when constructing the
    ``NeoPixel`` object.
 
+For low-level driving of a NeoPixel see `machine.bitstream`.
 
 APA102 driver
 -------------

docs/esp8266/tutorial/intro.rst

@@ -23,7 +23,7 @@ convertor to make the UART available to your PC.
 The minimum requirement for flash size is 1Mbyte. There is also a special
 build for boards with 512KB, but it is highly limited comparing to the
 normal build: there is no support for filesystem, and thus features which
-depend on it won't work (WebREPL, upip, etc.). As such, 512KB build will
+depend on it won't work (WebREPL, mip, etc.). As such, 512KB build will
 be more interesting for users who build from source and fine-tune parameters
 for their particular application.
 

docs/esp8266/tutorial/network_basics.rst

@@ -37,7 +37,7 @@ First activate the station interface::
 
 Then connect to your WiFi network::
 
-    >>> sta_if.connect('<your ESSID>', '<your password>')
+    >>> sta_if.connect('<your SSID>', '<your key>')
 
 To check if the connection is established use::
 
@@ -61,7 +61,7 @@ connect to your WiFi network::
         if not sta_if.isconnected():
             print('connecting to network...')
             sta_if.active(True)
-            sta_if.connect('<essid>', '<password>')
+            sta_if.connect('<ssid>', '<key>')
             while not sta_if.isconnected():
                 pass
         print('network config:', sta_if.ifconfig())

docs/index.rst

@@ -12,6 +12,9 @@ MicroPython documentation and references
     esp8266/quickref.rst
     esp32/quickref.rst
     rp2/quickref.rst
+    mimxrt/quickref.rst
     wipy/quickref.rst
     unix/quickref.rst
     zephyr/quickref.rst
+    renesas-ra/quickref.rst
+    samd/quickref.rst

docs/library/array.rst

@@ -27,3 +27,55 @@ Classes
 
         Append new elements as contained in *iterable* to the end of
         array, growing it.
+
+    .. method:: __getitem__(index)
+
+        Indexed read of the array, called as ``a[index]`` (where ``a`` is an ``array``).
+        Returns a value if *index* is an ``int`` and an ``array`` if *index* is a slice.
+        Negative indices count from the end and ``IndexError`` is thrown if the index is
+        out of range.
+
+        **Note:** ``__getitem__`` cannot be called directly (``a.__getitem__(index)`` fails) and
+        is not present in ``__dict__``, however ``a[index]`` does work.
+
+    .. method:: __setitem__(index, value)
+
+        Indexed write into the array, called as ``a[index] = value`` (where ``a`` is an ``array``).
+        ``value`` is a single value if *index* is an ``int`` and an ``array`` if *index* is a slice.
+        Negative indices count from the end and ``IndexError`` is thrown if the index is out of range.
+
+        **Note:** ``__setitem__`` cannot be called directly (``a.__setitem__(index, value)`` fails) and
+        is not present in ``__dict__``, however ``a[index] = value`` does work.
+
+    .. method:: __len__()
+
+        Returns the number of items in the array, called as ``len(a)`` (where ``a`` is an ``array``).
+
+        **Note:** ``__len__`` cannot be called directly (``a.__len__()`` fails) and the
+        method is not present in ``__dict__``, however ``len(a)`` does work.
+
+    .. method:: __add__(other)
+
+        Return a new ``array`` that is the concatenation of the array with *other*, called as
+        ``a + other`` (where ``a`` and *other* are both ``arrays``).
+
+        **Note:** ``__add__`` cannot be called directly (``a.__add__(other)`` fails) and
+        is not present in ``__dict__``, however ``a + other`` does work.
+
+    .. method:: __iadd__(other)
+
+        Concatenates the array with *other* in-place, called as ``a += other`` (where ``a`` and *other*
+        are both ``arrays``).  Equivalent to ``extend(other)``.
+
+        **Note:** ``__iadd__`` cannot be called directly (``a.__iadd__(other)`` fails) and
+        is not present in ``__dict__``, however ``a += other`` does work.
+
+    .. method:: __repr__()
+
+        Returns the string representation of the array, called as ``str(a)`` or ``repr(a)```
+        (where ``a`` is an ``array``).  Returns the string ``"array(<type>, [<elements>])"``,
+        where ``<type>`` is the type code letter for the array and ``<elements>`` is a comma
+        seperated list of the elements of the array.
+
+        **Note:** ``__repr__`` cannot be called directly (``a.__repr__()`` fails) and
+        is not present in ``__dict__``, however ``str(a)`` and ``repr(a)`` both work.

docs/library/binascii.rst

@@ -31,8 +31,8 @@ Functions
    Conforms to `RFC 2045 s.6.8 <https://tools.ietf.org/html/rfc2045#section-6.8>`_.
    Returns a bytes object.
 
-.. function:: b2a_base64(data)
+.. function:: b2a_base64(data, *, newline=True)
 
    Encode binary data in base64 format, as in `RFC 3548
    <https://tools.ietf.org/html/rfc3548.html>`_. Returns the encoded data
-   followed by a newline character, as a bytes object.
+   followed by a newline character if newline is true, as a bytes object.

docs/library/bluetooth.rst

@@ -13,6 +13,9 @@ concurrently. Pairing (and bonding) is supported on some ports.
 This API is intended to match the low-level Bluetooth protocol and provide
 building-blocks for higher-level abstractions such as specific device types.
 
+.. note:: For most applications, we recommend using the higher-level
+          `aioble library <https://github.com/micropython/micropython-lib/tree/master/micropython/bluetooth/aioble>`_.
+
 .. note:: This module is still under development and its classes, functions,
           methods and constants are subject to change.
 
@@ -163,7 +166,7 @@ Event Handling
                 conn_handle, status = data
             elif event == _IRQ_GATTC_CHARACTERISTIC_RESULT:
                 # Called for each characteristic found by gattc_discover_services().
-                conn_handle, def_handle, value_handle, properties, uuid = data
+                conn_handle, end_handle, value_handle, properties, uuid = data
             elif event == _IRQ_GATTC_CHARACTERISTIC_DONE:
                 # Called once service discovery is complete.
                 # Note: Status will be zero on success, implementation-specific value otherwise.
@@ -180,12 +183,10 @@ Event Handling
                 conn_handle, value_handle, char_data = data
             elif event == _IRQ_GATTC_READ_DONE:
                 # A gattc_read() has completed.
-                # Note: The value_handle will be zero on btstack (but present on NimBLE).
                 # Note: Status will be zero on success, implementation-specific value otherwise.
                 conn_handle, value_handle, status = data
             elif event == _IRQ_GATTC_WRITE_DONE:
                 # A gattc_write() has completed.
-                # Note: The value_handle will be zero on btstack (but present on NimBLE).
                 # Note: Status will be zero on success, implementation-specific value otherwise.
                 conn_handle, value_handle, status = data
             elif event == _IRQ_GATTC_NOTIFY:
@@ -511,19 +512,24 @@ writes from a client to a given characteristic, use
 
     Sends a notification request to a connected client.
 
-    If *data* is not ``None``, then that value is sent to the client as part of
-    the notification. The local value will not be modified.
+    If *data* is ``None`` (the default), then the current local value (as set
+    with :meth:`gatts_write <BLE.gatts_write>`) will be sent.
 
-    Otherwise, if *data* is ``None``, then the current local value (as
-    set with :meth:`gatts_write <BLE.gatts_write>`) will be sent.
+    Otherwise, if *data* is not ``None``, then that value is sent to the client
+    as part of the notification. The local value will not be modified.
 
     **Note:** The notification will be sent regardless of the subscription
     status of the client to this characteristic.
 
-.. method:: BLE.gatts_indicate(conn_handle, value_handle, /)
+.. method:: BLE.gatts_indicate(conn_handle, value_handle, data=None, /)
 
-    Sends an indication request containing the characteristic's current value to
-    a connected client.
+    Sends a indication request to a connected client.
+
+    If *data* is ``None`` (the default), then the current local value (as set
+    with :meth:`gatts_write <BLE.gatts_write>`) will be sent.
+
+    Otherwise, if *data* is not ``None``, then that value is sent to the client
+    as part of the indication. The local value will not be modified.
 
     On acknowledgment (or failure, e.g. timeout), the
     ``_IRQ_GATTS_INDICATE_DONE`` event will be raised.

docs/library/btree.rst

@@ -11,8 +11,9 @@ value, a database also supports efficient ordered range scans (retrieval
 of values with the keys in a given range). On the application interface
 side, BTree database work as close a possible to a way standard `dict`
 type works, one notable difference is that both keys and values must
-be `bytes` objects (so, if you want to store objects of other types, you
-need to serialize them to `bytes` first).
+be `bytes`-like objects (so, if you want to store objects of other types, you
+need to first serialize them to `str` or `bytes` or another type that supports
+the buffer protocol).
 
 The module is based on the well-known BerkelyDB library, version 1.xx.
 

docs/library/collections.rst

@@ -12,7 +12,7 @@ hold/accumulate various objects.
 Classes
 -------
 
-.. function:: deque(iterable, maxlen[, flags])
+.. class:: deque(iterable, maxlen[, flags])
 
     Deques (double-ended queues) are a list-like container that support O(1)
     appends and pops from either side of the deque.  New deques are created
@@ -57,7 +57,7 @@ Classes
         print(t1.name)
         assert t2.name == t2[1]
 
-.. function:: OrderedDict(...)
+.. class:: OrderedDict(...)
 
     ``dict`` type subclass which remembers and preserves the order of keys
     added. When ordered dict is iterated over, keys/items are returned in

docs/library/esp.rst

@@ -62,6 +62,21 @@ Functions
 
 .. function:: flash_erase(sector_no)
 
+.. function:: osdebug(level)
+
+    Turn esp os debugging messages on or off.
+
+    The *level* parameter sets the threshold for the log messages for all esp components.
+    The log levels are defined as constants:
+
+        * ``LOG_NONE`` -- No log output
+        * ``LOG_ERROR`` -- Critical errors, software module can not recover on its own
+        * ``LOG_WARN`` -- Error conditions from which recovery measures have been taken
+        * ``LOG_INFO`` -- Information messages which describe normal flow of events
+        * ``LOG_DEBUG`` -- Extra information which is not necessary for normal use (values, pointers, sizes, etc)
+        * ``LOG_VERBOSE`` -- Bigger chunks of debugging information, or frequent messages
+          which can potentially flood the output
+
 .. function:: set_native_code_location(start, length)
 
     **Note**: ESP8266 only

docs/library/esp32.rst

@@ -18,6 +18,11 @@ Functions
     Configure whether or not a touch will wake the device from sleep.
     *wake* should be a boolean value.
 
+.. function:: wake_on_ulp(wake)
+
+    Configure whether or not the Ultra-Low-Power co-processor can wake the
+    device from sleep. *wake* should be a boolean value.
+
 .. function:: wake_on_ext0(pin, level)
 
     Configure how EXT0 wakes the device from sleep.  *pin* can be ``None``
@@ -30,6 +35,11 @@ Functions
     or a tuple/list of valid Pin objects.  *level* should be ``esp32.WAKEUP_ALL_LOW``
     or ``esp32.WAKEUP_ANY_HIGH``.
 
+.. function:: gpio_deep_sleep_hold(enable)
+
+    Configure whether non-RTC GPIO pin configuration is retained during
+    deep-sleep mode for held pads. *enable* should be a boolean value.
+
 .. function:: raw_temperature()
 
     Read the raw value of the internal temperature sensor, returning an integer.
@@ -68,17 +78,21 @@ Flash partitions
 This class gives access to the partitions in the device's flash memory and includes
 methods to enable over-the-air (OTA) updates.
 
-.. class:: Partition(id)
+.. class:: Partition(id, block_size=4096, /)
 
     Create an object representing a partition.  *id* can be a string which is the label
     of the partition to retrieve, or one of the constants: ``BOOT`` or ``RUNNING``.
+    *block_size* specifies the byte size of an individual block.
 
-.. classmethod:: Partition.find(type=TYPE_APP, subtype=0xff, label=None)
+.. classmethod:: Partition.find(type=TYPE_APP, subtype=0xff, label=None, block_size=4096)
 
     Find a partition specified by *type*, *subtype* and *label*.  Returns a
     (possibly empty) list of Partition objects. Note: ``subtype=0xff`` matches any subtype
     and ``label=None`` matches any label.
 
+    *block_size* specifies the byte size of an individual block used by the returned
+    objects.
+
 .. method:: Partition.info()
 
     Returns a 6-tuple ``(type, subtype, addr, size, label, encrypted)``.

docs/library/framebuf.rst

@@ -11,8 +11,8 @@ class FrameBuffer
 -----------------
 
 The FrameBuffer class provides a pixel buffer which can be drawn upon with
-pixels, lines, rectangles, text and even other FrameBuffer's. It is useful
-when generating output for displays.
+pixels, lines, rectangles, ellipses, polygons, text and even other
+FrameBuffers. It is useful when generating output for displays.
 
 For example::
 
@@ -77,12 +77,37 @@ The following methods draw shapes onto the FrameBuffer.
     methods draw horizontal and vertical lines respectively up to
     a given length.
 
-.. method:: FrameBuffer.rect(x, y, w, h, c)
-.. method:: FrameBuffer.fill_rect(x, y, w, h, c)
+.. method:: FrameBuffer.rect(x, y, w, h, c[, f])
 
-    Draw a rectangle at the given location, size and color. The `rect`
-    method draws only a 1 pixel outline whereas the `fill_rect` method
-    draws both the outline and interior.
+    Draw a rectangle at the given location, size and color.
+
+    The optional *f* parameter can be set to ``True`` to fill the rectangle.
+    Otherwise just a one pixel outline is drawn.
+
+.. method:: FrameBuffer.ellipse(x, y, xr, yr, c[, f, m])
+
+    Draw an ellipse at the given location. Radii *xr* and *yr* define the
+    geometry; equal values cause a circle to be drawn. The *c* parameter
+    defines the color.
+
+    The optional *f* parameter can be set to ``True`` to fill the ellipse.
+    Otherwise just a one pixel outline is drawn.
+
+    The optional *m* parameter enables drawing to be restricted to certain
+    quadrants of the ellipse. The LS four bits determine which quadrants are
+    to be drawn, with bit 0 specifying Q1, b1 Q2, b2 Q3 and b3 Q4. Quadrants
+    are numbered counterclockwise with Q1 being top right.
+
+.. method:: FrameBuffer.poly(x, y, coords, c[, f])
+
+    Given a list of coordinates, draw an arbitrary (convex or concave) closed
+    polygon at the given x, y location using the given color.
+
+    The *coords* must be specified as a :mod:`array` of integers, e.g.
+    ``array('h', [x0, y0, x1, y1, ... xn, yn])``.
+
+    The optional *f* parameter can be set to ``True`` to fill the polygon.
+    Otherwise just a one pixel outline is drawn.
 
 Drawing text
 ------------
@@ -108,7 +133,9 @@ Other methods
     Draw another FrameBuffer on top of the current one at the given coordinates.
     If *key* is specified then it should be a color integer and the
     corresponding color will be considered transparent: all pixels with that
-    color value will not be drawn.
+    color value will not be drawn. (If the *palette* is specified then the *key*
+    is compared to the value from *palette*, not to the value directly from
+    *fbuf*.)
 
     The *palette* argument enables blitting between FrameBuffers with differing
     formats. Typical usage is to render a monochrome or grayscale glyph/icon to

docs/library/index.rst

@@ -97,6 +97,13 @@ the following libraries.
    network.rst
    uctypes.rst
 
+The following libraries provide drivers for hardware components.
+
+.. toctree::
+  :maxdepth: 1
+
+  wm8960.rst
+
 
 Port-specific libraries
 -----------------------
@@ -188,4 +195,4 @@ but also the MicroPython libraries too (e.g. ``machine``, ``bluetooth``, etc).
 The main exception is the port-specific libraries (``pyb``, ``esp``, etc).
 
 *Other than when you specifically want to force the use of the built-in module,
-we recommend always using ``import module`` rather than ``import umodule``.*
+we recommend always using* ``import module`` *rather than* ``import umodule``.

docs/library/machine.ADC.rst

@@ -8,28 +8,59 @@ The ADC class provides an interface to analog-to-digital convertors, and
 represents a single endpoint that can sample a continuous voltage and
 convert it to a discretised value.
 
+For extra control over ADC sampling see :ref:`machine.ADCBlock <machine.ADCBlock>`.
+
 Example usage::
 
-   import machine
+   from machine import ADC
 
-   adc = machine.ADC(pin)   # create an ADC object acting on a pin
-   val = adc.read_u16()     # read a raw analog value in the range 0-65535
+   adc = ADC(pin)        # create an ADC object acting on a pin
+   val = adc.read_u16()  # read a raw analog value in the range 0-65535
+   val = adc.read_uv()   # read an analog value in microvolts
 
 Constructors
 ------------
 
-.. class:: ADC(id)
+.. class:: ADC(id, *, sample_ns, atten)
 
    Access the ADC associated with a source identified by *id*.  This
    *id* may be an integer (usually specifying a channel number), a
    :ref:`Pin <machine.Pin>` object, or other value supported by the
    underlying machine.
 
+   If additional keyword-arguments are given then they will configure
+   various aspects of the ADC.  If not given, these settings will take
+   previous or default values.  The settings are:
+
+     - *sample_ns* is the sampling time in nanoseconds.
+
+     - *atten* specifies the input attenuation.
+
 Methods
 -------
 
+.. method:: ADC.init(*, sample_ns, atten)
+
+   Apply the given settings to the ADC.  Only those arguments that are
+   specified will be changed.  See the ADC constructor above for what the
+   arguments are.
+
+.. method:: ADC.block()
+
+   Return the :ref:`ADCBlock <machine.ADCBlock>` instance associated with
+   this ADC object.
+
+   This method only exists if the port supports the
+   :ref:`ADCBlock <machine.ADCBlock>` class.
+
 .. method:: ADC.read_u16()
 
    Take an analog reading and return an integer in the range 0-65535.
    The return value represents the raw reading taken by the ADC, scaled
    such that the minimum value is 0 and the maximum value is 65535.
+
+.. method:: ADC.read_uv()
+
+   Take an analog reading and return an integer value with units of
+   microvolts.  It is up to the particular port whether or not this value
+   is calibrated, and how calibration is done.

docs/library/machine.ADCBlock.rst

@@ -0,0 +1,58 @@
+.. currentmodule:: machine
+.. _machine.ADCBlock:
+
+class ADCBlock -- control ADC peripherals
+=========================================
+
+The ADCBlock class provides access to an ADC peripheral which has a
+number of channels that can be used to sample analog values.  It allows
+finer control over configuration of :ref:`machine.ADC <machine.ADC>`
+objects, which do the actual sampling.
+
+This class is not always available.
+
+Example usage::
+
+   from machine import ADCBlock
+
+   block = ADCBlock(id, bits=12)  # create an ADCBlock with 12-bit resolution
+   adc = block.connect(4, pin)    # connect channel 4 to the given pin
+   val = adc.read_uv()            # read an analog value
+
+Constructors
+------------
+
+.. class:: ADCBlock(id, *, bits)
+
+   Access the ADC peripheral identified by *id*, which may be an integer
+   or string.
+   
+   The *bits* argument, if given, sets the resolution in bits of the
+   conversion process.  If not specified then the previous or default
+   resolution is used.
+
+Methods
+-------
+
+.. method:: ADCBlock.init(*, bits)
+
+   Configure the ADC peripheral.  *bits* will set the resolution of the
+   conversion process.
+
+.. method:: ADCBlock.connect(channel)
+            ADCBlock.connect(source)
+            ADCBlock.connect(channel, source)
+
+   Connect up a channel on the ADC peripheral so it is ready for sampling,
+   and return an :ref:`ADC <machine.ADC>` object that represents that connection.
+
+   The *channel* argument must be an integer, and *source* must be an object
+   (for example a :ref:`Pin <machine.Pin>`) which can be connected up for sampling.
+
+   If only *channel* is given then it is configured for sampling.
+
+   If only *source* is given then that object is connected to a default
+   channel ready for sampling.
+
+   If both *channel* and *source* are given then they are connected together
+   and made ready for sampling.

docs/library/machine.I2C.rst

@@ -20,6 +20,17 @@ Software I2C is implemented by bit-banging and can be used on any pin but is not
 as efficient.  These classes have the same methods available and differ primarily
 in the way they are constructed.
 
+.. Note::
+
+   The I2C bus requires pull-up circuitry on both SDA and SCL for it's operation.
+   Usually these are resistors in the range of 1 - 10 kOhm, connected from each SDA/SCL
+   to Vcc. Without these, the behaviour is undefined and may range from blocking,
+   unexpected watchdog reset to just wrong values. Often, this pull-up circuitry
+   is built-in already to the MCU board or sensor breakout boards, but there is
+   no rule for that. So please check in case of trouble. See also this excellent
+   `learning guide <https://learn.adafruit.com/working-with-i2c-devices/pull-up-resistors>`_
+   by Adafruit about I2C wiring.
+
 Example usage::
 
     from machine import I2C
@@ -41,7 +52,7 @@ Example usage::
 Constructors
 ------------
 
-.. class:: I2C(id, *, scl, sda, freq=400000)
+.. class:: I2C(id, *, scl, sda, freq=400000, timeout=50000)
 
    Construct and return a new I2C object using the following parameters:
 
@@ -51,13 +62,15 @@ Constructors
       - *sda* should be a pin object specifying the pin to use for SDA.
       - *freq* should be an integer which sets the maximum frequency
         for SCL.
+      - *timeout* is the maximum time in microseconds to allow for I2C
+        transactions.  This parameter is not allowed on some ports.
 
    Note that some ports/boards will have default values of *scl* and *sda*
    that can be changed in this constructor.  Others will have fixed values
    of *scl* and *sda* that cannot be changed.
 
 .. _machine.SoftI2C:
-.. class:: SoftI2C(scl, sda, *, freq=400000, timeout=255)
+.. class:: SoftI2C(scl, sda, *, freq=400000, timeout=50000)
 
    Construct a new software I2C object.  The parameters are:
 
@@ -80,6 +93,10 @@ General Methods
      - *sda* is a pin object for the SDA line
      - *freq* is the SCL clock rate
 
+   In the case of hardware I2C the actual clock frequency may be lower than the
+   requested frequency. This is dependant on the platform hardware. The actual
+   rate may be determined by printing the I2C object.
+
 .. method:: I2C.deinit()
 
    Turn off the I2C bus.

docs/library/machine.I2S.rst

@@ -72,30 +72,34 @@ uasyncio::
    sreader = uasyncio.StreamReader(audio_in)
    num_read = await sreader.readinto(buf)
 
+Some codec devices like the WM8960 or SGTL5000 require separate initialization
+before they can operate with the I2S class.  For these, separate drivers are
+supplied, which also offer methods for controlling volume, audio processing and
+other things.  For these drivers see:
+
+- :ref:`wm8960`
+
 Constructor
 -----------
 
-.. class:: I2S(id, *, sck, ws, sd, mode, bits, format, rate, ibuf)
+.. class:: I2S(id, *, sck, ws, sd, mck=None, mode, bits, format, rate, ibuf)
 
    Construct an I2S object of the given id:
 
-   - ``id`` identifies a particular I2S bus.
-
-   ``id`` is board and port specific:
-
-     - PYBv1.0/v1.1: has one I2S bus with id=2.
-     - PYBD-SFxW: has two I2S buses with id=1 and id=2.
-     - ESP32: has two I2S buses with id=0 and id=1.
+   - ``id`` identifies a particular I2S bus; it is board and port specific
 
    Keyword-only parameters that are supported on all ports:
 
      - ``sck`` is a pin object for the serial clock line
      - ``ws`` is a pin object for the word select line
      - ``sd`` is a pin object for the serial data line
+     - ``mck`` is a pin object for the master clock line;
+       master clock frequency is sampling rate * 256
      - ``mode`` specifies receive or transmit
      - ``bits`` specifies sample size (bits), 16 or 32
      - ``format`` specifies channel format, STEREO or MONO
-     - ``rate`` specifies audio sampling rate (samples/s)
+     - ``rate`` specifies audio sampling rate (Hz);
+       this is the frequency of the ``ws`` signal
      - ``ibuf`` specifies internal buffer length (bytes)
 
    For all ports, DMA runs continuously in the background and allows user applications to perform other operations while

docs/library/machine.PWM.rst

@@ -23,7 +23,7 @@ Example usage::
 Constructors
 ------------
 
-.. class:: PWM(dest, \*, freq, duty_u16, duty_ns)
+.. class:: PWM(dest, *, freq, duty_u16, duty_ns)
 
    Construct and return a new PWM object using the following parameters:
 
@@ -42,7 +42,7 @@ Constructors
 Methods
 -------
 
-.. method:: PWM.init(\*, freq, duty_u16, duty_ns)
+.. method:: PWM.init(*, freq, duty_u16, duty_ns)
 
    Modify settings for the PWM object.  See the above constructor for details
    about the parameters.
@@ -78,6 +78,13 @@ Methods
 
    With a single *value* argument the pulse width is set to that value.
 
+Specific PWM class implementations
+----------------------------------
+
+The following concrete class(es) implement enhancements to the PWM class.
+
+   | :ref:`pyb.Timer for PyBoard <pyb.Timer>`  
+
 Limitations of PWM
 ------------------
 
@@ -90,6 +97,11 @@ Limitations of PWM
   80000000 / 267 = 299625.5 Hz, not 300kHz.  If the divider is set to 266 then
   the PWM frequency will be 80000000 / 266 = 300751.9 Hz, but again not 300kHz.
 
+  Some ports like the RP2040 one use a fractional divider, which allow a finer
+  granularity of the frequency at higher frequencies by switching the PWM
+  pulse duration between two adjacent values, such that the resulting average
+  frequency is more close to the intended one, at the cost of spectral purity. 
+
 * The duty cycle has the same discrete nature and its absolute accuracy is not
   achievable.  On most hardware platforms the duty will be applied at the next
   frequency period.  Therefore, you should wait more than "1/frequency" before

docs/library/machine.Pin.rst

@@ -42,7 +42,7 @@ Usage Model::
 Constructors
 ------------
 
-.. class:: Pin(id, mode=-1, pull=-1, *, value, drive, alt)
+.. class:: Pin(id, mode=-1, pull=-1, *, value=None, drive=0, alt=-1)
 
    Access the pin peripheral (GPIO pin) associated with the given ``id``.  If
    additional arguments are given in the constructor then they are used to initialise
@@ -87,9 +87,9 @@ Constructors
        output pin value if given, otherwise the state of the pin peripheral remains
        unchanged.
 
-     - ``drive`` specifies the output power of the pin and can be one of: ``Pin.LOW_POWER``,
-       ``Pin.MED_POWER`` or ``Pin.HIGH_POWER``.  The actual current driving capabilities
-       are port dependent.  Not all ports implement this argument.
+     - ``drive`` specifies the output power of the pin and can be one of: ``Pin.DRIVE_0``,
+       ``Pin.DRIVE_1``, etc., increasing in drive strength.  The actual current driving
+       capabilities are port dependent.  Not all ports implement this argument.
 
      - ``alt`` specifies an alternate function for the pin and the values it can take are
        port dependent.  This argument is valid only for ``Pin.ALT`` and ``Pin.ALT_OPEN_DRAIN``
@@ -108,7 +108,7 @@ Constructors
 Methods
 -------
 
-.. method:: Pin.init(mode=-1, pull=-1, *, value, drive, alt)
+.. method:: Pin.init(mode=-1, pull=-1, *, value=None, drive=0, alt=-1)
 
    Re-initialise the pin using the given parameters.  Only those arguments that
    are specified will be set.  The rest of the pin peripheral state will remain
@@ -260,11 +260,13 @@ not all constants are available on all ports.
    Selects whether there is a pull up/down resistor.  Use the value
    ``None`` for no pull.
 
-.. data:: Pin.LOW_POWER
-          Pin.MED_POWER
-          Pin.HIGH_POWER
+.. data:: Pin.DRIVE_0
+          Pin.DRIVE_1
+          Pin.DRIVE_2
 
-   Selects the pin drive strength.
+   Selects the pin drive strength.  A port may define additional drive
+   constants with increasing number corresponding to increasing drive
+   strength.
 
 .. data:: Pin.IRQ_FALLING
           Pin.IRQ_RISING

docs/library/machine.SDCard.rst

@@ -122,3 +122,46 @@ You can set the pins used for SPI access by passing a tuple as the
 
 *Note:* The current cc3200 SD card implementation names the this class
 :class:`machine.SD` rather than :class:`machine.SDCard` .
+
+mimxrt
+``````
+
+The SDCard module for the mimxrt port only supports access via dedicated SD/MMC
+peripheral (USDHC) in 4-bit mode with 50MHz clock frequency exclusively.
+Unfortunately the MIMXRT1011 controller does not support the USDHC peripheral.
+Hence this controller does not feature the ``machine.SDCard`` module.
+
+Due to the decision to only support 4-bit mode with 50MHz clock frequency the
+interface has been simplified, and the constructor signature is:
+
+.. class:: SDCard(slot=1)
+  :noindex:
+
+The pins used for the USDHC peripheral have to be configured in ``mpconfigboard.h``.
+Most of the controllers supported by the mimxrt port provide up to two USDHC
+peripherals.  Therefore the pin configuration is performed using the macro
+``MICROPY_USDHCx`` with x being 1 or 2 respectively.
+
+The following shows an example configuration for USDHC1::
+
+  #define MICROPY_USDHC1 \
+    { \
+          .cmd   = { GPIO_SD_B0_02_USDHC1_CMD}, \
+          .clk   = { GPIO_SD_B0_03_USDHC1_CLK }, \
+          .cd_b  = { GPIO_SD_B0_06_USDHC1_CD_B },\
+          .data0 = { GPIO_SD_B0_04_USDHC1_DATA0 },\
+          .data1 = { GPIO_SD_B0_05_USDHC1_DATA1 },\
+          .data2 = { GPIO_SD_B0_00_USDHC1_DATA2 },\
+          .data3 = { GPIO_SD_B0_01_USDHC1_DATA3 },\
+    }
+
+If the card detect pin is not used (cb_b pin) then the respective entry has to be
+filled with the following dummy value::
+
+  #define USDHC_DUMMY_PIN NULL , 0
+
+Based on the definition of macro ``MICROPY_USDHC1`` and/or ``MICROPY_USDHC2``
+the ``machine.SDCard`` module either supports one or two slots.  If only one of
+the defines is provided, calling ``machine.SDCard()`` or ``machine.SDCard(1)``
+will return an instance using the respective USDHC peripheral.  When both macros
+are defined, calling ``machine.SDCard(2)`` returns an instance using USDHC2.

docs/library/machine.SPI.rst

@@ -143,9 +143,11 @@ Constants
    for initialising the SPI bus to controller; this is only used for the WiPy
 
 .. data:: SPI.MSB
+          SoftSPI.MSB
 
    set the first bit to be the most significant bit
 
 .. data:: SPI.LSB
+          SoftSPI.LSB
 
    set the first bit to be the least significant bit

docs/library/machine.Timer.rst

@@ -38,13 +38,16 @@ Constructors
 Methods
 -------
 
-.. method:: Timer.init(*, mode=Timer.PERIODIC, period=-1, callback=None)
+.. method:: Timer.init(*, mode=Timer.PERIODIC, freq=-1, period=-1, callback=None)
 
    Initialise the timer. Example::
 
        def mycallback(t):
            pass
 
+       # periodic at 1kHz
+       tim.init(mode=Timer.PERIODIC, freq=1000, callback=mycallback)
+
        # periodic with 100ms period
        tim.init(period=100, callback=mycallback)
 
@@ -60,6 +63,11 @@ Methods
        - ``Timer.PERIODIC`` - The timer runs periodically at the configured
          frequency of the channel.
 
+     - ``freq`` - The timer frequency, in units of Hz.  The upper bound of
+       the frequency is dependent on the port.  When both the ``freq`` and
+       ``period`` arguments are given, ``freq`` has a higher priority and
+       ``period`` is ignored.
+
      - ``period`` - The timer period, in milliseconds.
 
      - ``callback`` - The callable to call upon expiration of the timer period.

docs/library/machine.UART.rst

@@ -63,6 +63,12 @@ Methods
      - *timeout* specifies the time to wait for the first character (in ms).
      - *timeout_char* specifies the time to wait between characters (in ms).
      - *invert* specifies which lines to invert.
+
+         - ``0`` will not invert lines (idle state of both lines is logic high).
+         - ``UART.INV_TX`` will invert TX line (idle state of TX line now logic low).
+         - ``UART.INV_RX`` will invert RX line (idle state of RX line now logic low).
+         - ``UART.INV_TX | UART.INV_RX`` will invert both lines (idle state at logic low).
+
      - *flow* specifies which hardware flow control signals to use. The value
        is a bitmask.
 
@@ -81,10 +87,22 @@ Methods
        When no pins are given, then the default set of TX and RX pins is taken, and hardware
        flow control will be disabled. If *pins* is ``None``, no pin assignment will be made.
 
+   .. note::
+     It is possible to call ``init()`` multiple times on the same object in
+     order to reconfigure  UART on the fly. That allows using single UART
+     peripheral to serve different devices attached to different GPIO pins.
+     Only one device can be served at a time in that case.
+     Also do not call ``deinit()`` as it will prevent calling ``init()``
+     again.
+
 .. method:: UART.deinit()
 
    Turn off the UART bus.
 
+   .. note::
+     You will not be able to call ``init()`` on the object after ``deinit()``.
+     A new instance needs to be created in that case.
+
 .. method:: UART.any()
 
    Returns an integer counting the number of characters that can be read without
@@ -159,6 +177,32 @@ Methods
 
    Availability: WiPy.
 
+.. method:: UART.flush()
+
+   Waits until all data has been sent. In case of a timeout, an exception is raised. The timeout
+   duration depends on the tx buffer size and the baud rate. Unless flow control is enabled, a timeout
+   should not occur.
+
+   .. note::
+
+       For the rp2, esp8266 and nrf ports the call returns while the last byte is sent.
+       If required, a one character wait time has to be added in the calling script.
+
+   Availability: rp2, esp32, esp8266, mimxrt, cc3200, stm32, nrf ports, renesas-ra
+
+.. method:: UART.txdone()
+
+   Tells whether all data has been sent or no data transfer is happening. In this case,
+   it returns ``True``. If a data transmission is ongoing it returns ``False``.
+
+   .. note::
+
+       For the rp2, esp8266 and nrf ports the call may return ``True`` even if the last byte
+       of a transfer is still being sent. If required, a one character wait time has to be
+       added in the calling script.
+
+   Availability: rp2, esp32, esp8266, mimxrt, cc3200, stm32, nrf ports, renesas-ra
+
 Constants
 ---------
 

docs/library/machine.WDT.rst

@@ -15,7 +15,7 @@ Example usage::
     wdt = WDT(timeout=2000)  # enable it with a timeout of 2s
     wdt.feed()
 
-Availability of this class: pyboard, WiPy, esp8266, esp32.
+Availability of this class: pyboard, WiPy, esp8266, esp32, rp2040, mimxrt.
 
 Constructors
 ------------
@@ -26,12 +26,13 @@ Constructors
    Once it is running the timeout cannot be changed and the WDT cannot be stopped either.
 
    Notes: On the esp32 the minimum timeout is 1 second. On the esp8266 a timeout
-   cannot be specified, it is determined by the underlying system.
+   cannot be specified, it is determined by the underlying system. On rp2040 devices,
+   the maximum timeout is 8388 ms.
 
 Methods
 -------
 
-.. method:: wdt.feed()
+.. method:: WDT.feed()
 
    Feed the WDT to prevent it from resetting the system. The application
    should place this call in a sensible place ensuring that the WDT is

docs/library/machine.rst

@@ -19,6 +19,44 @@ This is true for both physical devices with IDs >= 0 and "virtual" devices
 with negative IDs like -1 (these "virtual" devices are still thin shims on
 top of real hardware and real hardware interrupts). See :ref:`isr_rules`.
 
+Memory access
+-------------
+
+The module exposes three objects used for raw memory access.
+
+.. data:: mem8
+
+    Read/write 8 bits of memory.
+
+.. data:: mem16
+
+    Read/write 16 bits of memory.
+
+.. data:: mem32
+
+    Read/write 32 bits of memory.
+
+Use subscript notation ``[...]`` to index these objects with the address of
+interest. Note that the address is the byte address, regardless of the size of
+memory being accessed.
+
+Example use (registers are specific to an stm32 microcontroller):
+
+.. code-block:: python3
+
+    import machine
+    from micropython import const
+
+    GPIOA = const(0x48000000)
+    GPIO_BSRR = const(0x18)
+    GPIO_IDR = const(0x10)
+
+    # set PA2 high
+    machine.mem32[GPIOA + GPIO_BSRR] = 1 << 2
+
+    # read PA3
+    value = (machine.mem32[GPIOA + GPIO_IDR] >> 3) & 1
+
 Reset related functions
 -----------------------
 
@@ -48,6 +86,23 @@ Reset related functions
 Interrupt related functions
 ---------------------------
 
+The following functions allow control over interrupts.  Some systems require
+interrupts to operate correctly so disabling them for long periods may
+compromise core functionality, for example watchdog timers may trigger
+unexpectedly.  Interrupts should only be disabled for a minimum amount of time
+and then re-enabled to their previous state.  For example::
+
+    import machine
+
+    # Disable interrupts
+    state = machine.disable_irq()
+
+    # Do a small amount of time-critical work here
+
+    # Enable interrupts
+    machine.enable_irq(state)
+
+
 .. function:: disable_irq()
 
    Disable interrupt requests.
@@ -199,6 +254,7 @@ Classes
    machine.Pin.rst
    machine.Signal.rst
    machine.ADC.rst
+   machine.ADCBlock.rst
    machine.PWM.rst
    machine.UART.rst
    machine.SPI.rst

docs/library/micropython.rst

@@ -9,7 +9,7 @@ Functions
 
 .. function:: const(expr)
 
-   Used to declare that the expression is a constant so that the compile can
+   Used to declare that the expression is a constant so that the compiler can
    optimise it.  The use of this function should be as follows::
 
     from micropython import const

docs/library/neopixel.rst

@@ -6,9 +6,11 @@
 
 This module provides a driver for WS2818 / NeoPixel LEDs.
 
-.. note:: This module is only included by default on the ESP8266 and ESP32
-   ports. On STM32 / Pyboard, you can `download the module
-   <https://github.com/micropython/micropython/blob/master/drivers/neopixel/neopixel.py>`_
+.. note:: This module is only included by default on the ESP8266, ESP32 and RP2
+   ports. On STM32 / Pyboard and others, you can either install the
+   ``neopixel`` package using :term:`mip`, or you can download the module
+   directly from
+   <https://raw.githubusercontent.com/micropython/micropython-lib/master/micropython/drivers/led/neopixel/neopixel.py>`_
    and copy it to the filesystem.
 
 class NeoPixel

docs/library/network.CC3K.rst

@@ -1,89 +0,0 @@
-.. currentmodule:: network
-.. _network.CC3K:
-
-class CC3K -- control CC3000 WiFi modules
-=========================================
-
-This class provides a driver for CC3000 WiFi modules.  Example usage::
-
-    import network
-    nic = network.CC3K(pyb.SPI(2), pyb.Pin.board.Y5, pyb.Pin.board.Y4, pyb.Pin.board.Y3)
-    nic.connect('your-ssid', 'your-password')
-    while not nic.isconnected():
-        pyb.delay(50)
-    print(nic.ifconfig())
-
-    # now use socket as usual
-    ...
-
-For this example to work the CC3000 module must have the following connections:
-
-    - MOSI connected to Y8
-    - MISO connected to Y7
-    - CLK connected to Y6
-    - CS connected to Y5
-    - VBEN connected to Y4
-    - IRQ connected to Y3
-
-It is possible to use other SPI buses and other pins for CS, VBEN and IRQ.
-
-Constructors
-------------
-
-.. class:: CC3K(spi, pin_cs, pin_en, pin_irq)
-
-   Create a CC3K driver object, initialise the CC3000 module using the given SPI bus
-   and pins, and return the CC3K object.
-
-   Arguments are:
-
-     - *spi* is an :ref:`SPI object <pyb.SPI>` which is the SPI bus that the CC3000 is
-       connected to (the MOSI, MISO and CLK pins).
-     - *pin_cs* is a :ref:`Pin object <pyb.Pin>` which is connected to the CC3000 CS pin.
-     - *pin_en* is a :ref:`Pin object <pyb.Pin>` which is connected to the CC3000 VBEN pin.
-     - *pin_irq* is a :ref:`Pin object <pyb.Pin>` which is connected to the CC3000 IRQ pin.
-
-   All of these objects will be initialised by the driver, so there is no need to
-   initialise them yourself.  For example, you can use::
-
-     nic = network.CC3K(pyb.SPI(2), pyb.Pin.board.Y5, pyb.Pin.board.Y4, pyb.Pin.board.Y3)
-
-Methods
--------
-
-.. method:: CC3K.connect(ssid, key=None, *, security=WPA2, bssid=None)
-
-   Connect to a WiFi access point using the given SSID, and other security
-   parameters.
-
-.. method:: CC3K.disconnect()
-
-   Disconnect from the WiFi access point.
-
-.. method:: CC3K.isconnected()
-
-   Returns True if connected to a WiFi access point and has a valid IP address,
-   False otherwise.
-
-.. method:: CC3K.ifconfig()
-
-   Returns a 7-tuple with (ip, subnet mask, gateway, DNS server, DHCP server,
-   MAC address, SSID).
-
-.. method:: CC3K.patch_version()
-
-   Return the version of the patch program (firmware) on the CC3000.
-
-.. method:: CC3K.patch_program('pgm')
-
-   Upload the current firmware to the CC3000.  You must pass 'pgm' as the first
-   argument in order for the upload to proceed.
-
-Constants
----------
-
-.. data:: CC3K.WEP
-.. data:: CC3K.WPA
-.. data:: CC3K.WPA2
-
-   security type to use

docs/library/network.LAN.rst

@@ -0,0 +1,95 @@
+.. currentmodule:: network
+.. _network.LAN:
+
+class LAN -- control an Ethernet module
+=======================================
+
+This class allows you to control the Ethernet interface. The PHY hardware type is board-specific.
+
+Example usage::
+
+    import network
+    nic = network.LAN(0)
+    print(nic.ifconfig())
+
+    # now use socket as usual
+    ...
+
+
+Constructors
+------------
+
+.. class:: LAN(id, *, phy_type=<board_default>, phy_addr=<board_default>, ref_clk_mode=<board_default>)
+
+   Create a LAN driver object, initialise the LAN module using the given
+   PHY driver name, and return the LAN object.
+
+   Arguments are:
+
+     - *id* is the number of the Ethernet port, either 0 or 1.
+     - *phy_type* is the name of the PHY driver. For most board the on-board PHY has to be used and
+       is the default. Suitable values are port specific.
+     - *phy_addr* specifies the address of the PHY interface. As with *phy_type*, the hardwired value has
+       to be used for most boards and that value is the default.
+     - *ref_clk_mode* specifies, whether the data clock is provided by the Ethernet controller or
+       the PYH interface.
+       The default value is the one that matches the board. If set to ``LAN.OUT`` or ``Pin.OUT``
+       or ``True``, the clock is driven by the Ethernet controller, if set to ``LAN.IN``
+       or ``Pin.IN`` or ``False``, the clock is driven by the PHY interface.
+
+   For example, with the Seeed Arch Mix board you can  use::
+
+     nic = LAN(0, phy_type=LAN.PHY_LAN8720, phy_addr=1, ref_clk_mode=Pin.IN)
+
+Methods
+-------
+
+.. method:: LAN.active([state])
+
+   With a parameter, it sets the interface active if *state* is true, otherwise it
+   sets it inactive.
+   Without a parameter, it returns the state.
+
+.. method:: LAN.isconnected()
+
+   Returns ``True`` if the physical Ethernet link is connected and up.
+   Returns ``False`` otherwise.
+
+.. method:: LAN.status()
+
+   Returns the LAN status.
+
+.. method:: LAN.ifconfig([(ip, subnet, gateway, dns)])
+
+   Get/set IP address, subnet mask, gateway and DNS.
+
+   When called with no arguments, this method returns a 4-tuple with the above information.
+
+   To set the above values, pass a 4-tuple with the required information.  For example::
+
+    nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
+
+.. method:: LAN.config(config_parameters)
+
+   Sets or gets parameters of the LAN interface. The only parameter that can be
+   retrieved is the MAC address, using::
+
+      mac = LAN.config("mac")
+
+   The parameters that can be set are:
+
+    - ``trace=n`` sets trace levels; suitable values are:
+
+        - 2: trace TX
+        - 4: trace RX
+        - 8: full trace
+
+    - ``low_power=bool`` sets or clears low power mode, valid values being ``False``
+      or ``True``.
+
+
+Specific LAN class implementations
+----------------------------------
+
+On the mimxrt port, suitable values for the *phy_type* constructor argument are:
+``PHY_KSZ8081``, ``PHY_DP83825``, ``PHY_DP83848``, ``PHY_LAN8720``, ``PHY_RTL8211F``.

docs/library/network.WIZNET5K.rst

@@ -6,7 +6,7 @@ class WIZNET5K -- control WIZnet5x00 Ethernet modules
 
 This class allows you to control WIZnet5x00 Ethernet adaptors based on
 the W5200 and W5500 chipsets.  The particular chipset that is supported
-by the firmware is selected at compile-time via the MICROPY_PY_WIZNET5K
+by the firmware is selected at compile-time via the MICROPY_PY_NETWORK_WIZNET5K
 option.
 
 Example usage::

docs/library/network.WLAN.rst

@@ -10,7 +10,7 @@ This class provides a driver for WiFi network processors.  Example usage::
     # enable station interface and connect to WiFi access point
     nic = network.WLAN(network.STA_IF)
     nic.active(True)
-    nic.connect('your-ssid', 'your-password')
+    nic.connect('your-ssid', 'your-key')
     # now use sockets as usual
 
 Constructors
@@ -32,9 +32,9 @@ Methods
     argument is passed. Otherwise, query current state if no argument is
     provided. Most other methods require active interface.
 
-.. method:: WLAN.connect(ssid=None, password=None, *, bssid=None)
+.. method:: WLAN.connect(ssid=None, key=None, *, bssid=None)
 
-    Connect to the specified wireless network, using the specified password.
+    Connect to the specified wireless network, using the specified key.
     If *bssid* is given then the connection will be restricted to the
     access-point with that MAC address (the *ssid* must also be specified
     in this case).
@@ -52,12 +52,12 @@ Methods
     Scanning is only possible on STA interface. Returns list of tuples with
     the information about WiFi access points:
 
-        (ssid, bssid, channel, RSSI, authmode, hidden)
+        (ssid, bssid, channel, RSSI, security, hidden)
 
     *bssid* is hardware address of an access point, in binary form, returned as
     bytes object. You can use `binascii.hexlify()` to convert it to ASCII form.
 
-    There are five values for authmode:
+    There are five values for security:
 
         * 0 -- open
         * 1 -- WEP
@@ -112,10 +112,10 @@ Methods
    multiple parameters can be set at once. For querying, parameters name should
    be quoted as a string, and only one parameter can be queries at time::
 
-    # Set WiFi access point name (formally known as ESSID) and WiFi channel
-    ap.config(essid='My AP', channel=11)
+    # Set WiFi access point name (formally known as SSID) and WiFi channel
+    ap.config(ssid='My AP', channel=11)
     # Query params one by one
-    print(ap.config('essid'))
+    print(ap.config('ssid'))
     print(ap.config('channel'))
 
    Following are commonly supported parameters (availability of a specific parameter
@@ -125,11 +125,12 @@ Methods
    Parameter      Description
    =============  ===========
    mac            MAC address (bytes)
-   essid          WiFi access point name (string)
+   ssid           WiFi access point name (string)
    channel        WiFi channel (integer)
-   hidden         Whether ESSID is hidden (boolean)
-   authmode       Authentication mode supported (enumeration, see module constants)
-   password       Access password (string)
-   dhcp_hostname  The DHCP hostname to use
+   hidden         Whether SSID is hidden (boolean)
+   security       Security protocol supported (enumeration, see module constants)
+   key            Access key (string)
+   hostname       The hostname that will be sent to DHCP (STA interfaces) and mDNS (if supported, both STA and AP). (Deprecated, use :func:`network.hostname` instead)
    reconnects     Number of reconnect attempts to make (integer, 0=none, -1=unlimited)
+   txpower        Maximum transmit power in dBm (integer or float)
    =============  ===========

docs/library/network.rst

@@ -89,7 +89,7 @@ parameter should be `id`.
        network media, there are different variants of predefined/
        recommended tuple formats, among them:
 
-       * WiFi: (ssid, bssid, channel, RSSI, authmode, hidden). There
+       * WiFi: (ssid, bssid, channel, RSSI, security, hidden). There
          may be further fields, specific to a particular device.
 
        The function may accept additional keyword arguments to filter scan
@@ -133,10 +133,10 @@ parameter should be `id`.
        querying, a parameter name should be quoted as a string, and only one
        parameter can be queried at a time::
 
-        # Set WiFi access point name (formally known as ESSID) and WiFi channel
-        ap.config(essid='My AP', channel=11)
+        # Set WiFi access point name (formally known as SSID) and WiFi channel
+        ap.config(ssid='My AP', channel=11)
         # Query params one by one
-        print(ap.config('essid'))
+        print(ap.config('ssid'))
         print(ap.config('channel'))
 
 Specific network class implementations
@@ -150,20 +150,47 @@ provide a way to control networking interfaces of various kinds.
 
    network.WLAN.rst
    network.WLANWiPy.rst
-   network.CC3K.rst
    network.WIZNET5K.rst
+   network.LAN.rst
 
 Network functions
 =================
 
 The following are functions available in the network module.
 
+.. function:: country([code])
+
+    Get or set the two-letter ISO 3166-1 Alpha-2 country code to be used for
+    radio compliance.
+
+    If the *code* parameter is provided, the country will be set to this value.
+    If the function is called without parameters, it returns the current
+    country.
+
+    The default code ``"XX"`` represents the "worldwide" region.
+
+.. function:: hostname([name])
+
+    Get or set the hostname that will identify this device on the network. It is
+    applied to all interfaces.
+
+    This hostname is used for:
+     * Sending to the DHCP server in the client request. (If using DHCP)
+     * Broadcasting via mDNS. (If enabled)
+
+    If the *name* parameter is provided, the hostname will be set to this value.
+    If the function is called without parameters, it returns the current
+    hostname.
+
+    The default hostname is typically the name of the board.
+
 .. function:: phy_mode([mode])
 
     Get or set the PHY mode.
 
-    If the *mode* parameter is provided, sets the mode to its value. If
-    the function is called without parameters, returns the current mode.
+    If the *mode* parameter is provided, the PHY mode will be set to this value.
+    If the function is called without parameters, it returns the current PHY
+    mode.
 
     The possible modes are defined as constants:
         * ``MODE_11B`` -- IEEE 802.11b,

docs/library/pyb.ADC.rst

@@ -23,7 +23,7 @@ Usage::
 Constructors
 ------------
 
-.. class:: pyb.ADC(pin)
+.. class:: ADC(pin)
 
    Create an ADC object associated with the given pin.
    This allows you to then read analog values on that pin.

docs/library/pyb.Accel.rst

@@ -16,7 +16,7 @@ Raw values are between -32 and 31.
 Constructors
 ------------
 
-.. class:: pyb.Accel()
+.. class:: Accel()
 
    Create and return an accelerometer object.
 

docs/library/pyb.CAN.rst

@@ -4,13 +4,12 @@
 class CAN -- controller area network communication bus
 ======================================================
 
-CAN implements the standard CAN communications protocol.  At
-the physical level it consists of 2 lines: RX and TX.  Note that
-to connect the pyboard to a CAN bus you must use a CAN transceiver
-to convert the CAN logic signals from the pyboard to the correct
+CAN implements support for classic CAN (available on F4, F7 MCUs) and CAN FD (H7 series) controllers.
+At the physical level CAN bus consists of 2 lines: RX and TX.  Note that to connect the pyboard to a
+CAN bus you must use a CAN transceiver to convert the CAN logic signals from the pyboard to the correct
 voltage levels on the bus.
 
-Example usage (works without anything connected)::
+Example usage for classic CAN controller in Loopback (transceiver-less) mode::
 
     from pyb import CAN
     can = CAN(1, CAN.LOOPBACK)
@@ -18,11 +17,21 @@ Example usage (works without anything connected)::
     can.send('message!', 123)   # send a message with id 123
     can.recv(0)                 # receive message on FIFO 0
 
+Example usage for CAN FD controller with all of the possible options enabled::
+
+    # FD frame + BRS mode + Extended frame ID. 500 Kbit/s for arbitration phase, 1Mbit/s for data phase.
+    can = CAN(1, CAN.NORMAL, baudrate=500_000, brs_baudrate=1_000_000, sample_point=80)
+    can.setfilter(0, CAN.RANGE, 0, (0xFFF0, 0xFFFF))
+    can.send('a'*64, 0xFFFF, fdf=True, brs=True, extframe=True)
+    can.recv(0)
+
+The following CAN module functions and their arguments are available
+for both classic and FD CAN controllers, unless otherwise stated.
 
 Constructors
 ------------
 
-.. class:: pyb.CAN(bus, ...)
+.. class:: CAN(bus, ...)
 
    Construct a CAN object on the given bus.  *bus* can be 1-2, or ``'YA'`` or ``'YB'``.
    With no additional parameters, the CAN object is created but not
@@ -35,43 +44,48 @@ Constructors
      - ``CAN(1)`` is on ``YA``: ``(RX, TX) = (Y3, Y4) = (PB8, PB9)``
      - ``CAN(2)`` is on ``YB``: ``(RX, TX) = (Y5, Y6) = (PB12, PB13)``
 
-Class Methods
--------------
-.. classmethod:: CAN.initfilterbanks(nr)
-
-   Reset and disable all filter banks and assign how many banks should be available for CAN(1).
-
-   STM32F405 has 28 filter banks that are shared between the two available CAN bus controllers.
-   This function configures how many filter banks should be assigned to each. *nr* is the number of banks
-   that will be assigned to CAN(1), the rest of the 28 are assigned to CAN(2).
-   At boot, 14 banks are assigned to each controller.
-
 Methods
 -------
 
-.. method:: CAN.init(mode, extframe=False, prescaler=100, *, sjw=1, bs1=6, bs2=8, auto_restart=False, baudrate=0, sample_point=75)
+.. method:: CAN.init(mode, prescaler=100, *, sjw=1, bs1=6, bs2=8, auto_restart=False, baudrate=0, sample_point=75,
+        num_filter_banks=14, brs_sjw=1, brs_bs1=8, brs_bs2=3, brs_baudrate=0, brs_sample_point=75)
 
    Initialise the CAN bus with the given parameters:
 
      - *mode* is one of:  NORMAL, LOOPBACK, SILENT, SILENT_LOOPBACK
-     - if *extframe* is True then the bus uses extended identifiers in the frames
-       (29 bits); otherwise it uses standard 11 bit identifiers
-     - *prescaler* is used to set the duration of 1 time quanta; the time quanta
-       will be the input clock (PCLK1, see :meth:`pyb.freq()`) divided by the prescaler
-     - *sjw* is the resynchronisation jump width in units of the time quanta;
-       it can be 1, 2, 3, 4
-     - *bs1* defines the location of the sample point in units of the time quanta;
-       it can be between 1 and 1024 inclusive
-     - *bs2* defines the location of the transmit point in units of the time quanta;
-       it can be between 1 and 16 inclusive
+     - *prescaler* is the value by which the CAN input clock is divided to generate the
+       nominal bit time quanta. The prescaler can be a value between 1 and 1024 inclusive
+       for classic CAN, and between 1 and 512 inclusive for CAN FD.
+     - *sjw* is the resynchronisation jump width in units of time quanta for nominal bits;
+       it can be a value between 1 and 4 inclusive for classic CAN, and between 1 and 128 inclusive for CAN FD.
+     - *bs1* defines the location of the sample point in units of the time quanta for nominal bits;
+       it can be a value between 1 and 16 inclusive for classic CAN, and between 2 and 256 inclusive for CAN FD.
+     - *bs2* defines the location of the transmit point in units of the time quanta for nominal bits;
+       it can be a value between 1 and 8 inclusive for classic CAN, and between 2 and 128 inclusive for CAN FD.
      - *auto_restart* sets whether the controller will automatically try and restart
        communications after entering the bus-off state; if this is disabled then
        :meth:`~CAN.restart()` can be used to leave the bus-off state
      - *baudrate* if a baudrate other than 0 is provided, this function will try to automatically
-       calculate a CAN bit-timing (overriding *prescaler*, *bs1* and *bs2*) that satisfies both
-       the baudrate and the desired *sample_point*.
-     - *sample_point* given in a percentage of the bit time, the *sample_point* specifies the position
-       of the last bit sample with respect to the whole bit time. The default *sample_point* is 75%.
+       calculate the CAN nominal bit time (overriding *prescaler*, *bs1* and *bs2*) that satisfies
+       both the baudrate and the desired *sample_point*.
+     - *sample_point* given in a percentage of the nominal bit time, the *sample_point* specifies the position
+       of the bit sample with respect to the whole nominal bit time. The default *sample_point* is 75%.
+     - *num_filter_banks* for classic CAN, this is the number of banks that will be assigned to CAN(1),
+       the rest of the 28 are assigned to CAN(2).
+     - *brs_prescaler* is the value by which the CAN FD input clock is divided to generate the
+       data bit time quanta. The prescaler can be a value between 1 and 32 inclusive.
+     - *brs_sjw* is the resynchronisation jump width in units of time quanta for data bits;
+       it can be a value between 1 and 16 inclusive
+     - *brs_bs1* defines the location of the sample point in units of the time quanta for data bits;
+       it can be a value between 1 and 32 inclusive
+     - *brs_bs2* defines the location of the transmit point in units of the time quanta for data bits;
+       it can be a value between 1 and 16 inclusive
+     - *brs_baudrate* if a baudrate other than 0 is provided, this function will try to automatically
+       calculate the CAN data bit time (overriding *brs_prescaler*, *brs_bs1* and *brs_bs2*) that satisfies
+       both the baudrate and the desired *brs_sample_point*.
+     - *brs_sample_point* given in a percentage of the data bit time, the *brs_sample_point* specifies the position
+       of the bit sample with respect to the whole data bit time. The default *brs_sample_point* is 75%.
+
 
    The time quanta tq is the basic unit of time for the CAN bus.  tq is the CAN
    prescaler value divided by PCLK1 (the frequency of internal peripheral bus 1);
@@ -140,17 +154,17 @@ Methods
    - number of pending RX messages on fifo 0
    - number of pending RX messages on fifo 1
 
-.. method:: CAN.setfilter(bank, mode, fifo, params, *, rtr)
+.. method:: CAN.setfilter(bank, mode, fifo, params, *, rtr, extframe=False)
 
    Configure a filter bank:
 
-   - *bank* is the filter bank that is to be configured.
-   - *mode* is the mode the filter should operate in.
+   - *bank* is the classic CAN controller filter bank, or CAN FD filter index, to configure.
+   - *mode* is the mode the filter should operate in, see the tables below.
    - *fifo* is which fifo (0 or 1) a message should be stored in, if it is accepted by this filter.
    - *params* is an array of values the defines the filter. The contents of the array depends on the *mode* argument.
 
    +-----------+---------------------------------------------------------+
-   |*mode*     |contents of *params* array                               |
+   |*mode*     |Contents of *params* array for classic CAN controller    |
    +===========+=========================================================+
    |CAN.LIST16 |Four 16 bit ids that will be accepted                    |
    +-----------+---------------------------------------------------------+
@@ -165,10 +179,20 @@ Methods
    |CAN.MASK32 |As with CAN.MASK16 but with only one 32 bit id/mask pair.|
    +-----------+---------------------------------------------------------+
 
-   - *rtr* is an array of booleans that states if a filter should accept a
-     remote transmission request message.  If this argument is not given
-     then it defaults to ``False`` for all entries.  The length of the array
-     depends on the *mode* argument.
+   +-----------+---------------------------------------------------------+
+   |*mode*     |Contents of *params* array for CAN FD controller         |
+   +===========+=========================================================+
+   |CAN.RANGE  |Two ids that represent a range of accepted ids.          |
+   +-----------+---------------------------------------------------------+
+   |CAN.DUAL   |Two ids that will be accepted. For example (1, 2)        |
+   +-----------+---------------------------------------------------------+
+   |CAN.MASK   |One filter ID and a mask. For example (0x111, 0x7FF)     |
+   +-----------+---------------------------------------------------------+
+
+   - *rtr* For classic CAN controllers, this is an array of booleans that states if
+     a filter should accept a remote transmission request message. If this argument
+     is not given then it defaults to ``False`` for all entries. The length of the
+     array depends on the *mode* argument. For CAN FD, this argument is ignored.
 
    +-----------+----------------------+
    |*mode*     |length of *rtr* array |
@@ -182,11 +206,17 @@ Methods
    |CAN.MASK32 |1                     |
    +-----------+----------------------+
 
-.. method:: CAN.clearfilter(bank)
+   - *extframe* If True the frame will have an extended identifier (29 bits),
+     otherwise a standard identifier (11 bits) is used.
+
+
+.. method:: CAN.clearfilter(bank, extframe=False)
 
    Clear and disables a filter bank:
 
-   - *bank* is the filter bank that is to be cleared.
+   - *bank* is the classic CAN controller filter bank, or CAN FD filter index, to clear.
+   - *extframe* For CAN FD controllers, if True, clear an extended filter (configured with extframe=True),
+     otherwise the clear a standard identifier (configured with extframe=False).
 
 .. method:: CAN.any(fifo)
 
@@ -200,32 +230,33 @@ Methods
      - *list* is an optional list object to be used as the return value
      - *timeout* is the timeout in milliseconds to wait for the receive.
 
-   Return value: A tuple containing four values.
+   Return value: A tuple containing five values.
 
      - The id of the message.
+     - A boolean that indicates if the message ID is standard or extended.
      - A boolean that indicates if the message is an RTR message.
      - The FMI (Filter Match Index) value.
      - An array containing the data.
 
    If *list* is ``None`` then a new tuple will be allocated, as well as a new
-   bytes object to contain the data (as the fourth element in the tuple).
+   bytes object to contain the data (as the fifth element in the tuple).
 
-   If *list* is not ``None`` then it should be a list object with a least four
-   elements.  The fourth element should be a memoryview object which is created
+   If *list* is not ``None`` then it should be a list object with a least five
+   elements.  The fifth element should be a memoryview object which is created
    from either a bytearray or an array of type 'B' or 'b', and this array must
    have enough room for at least 8 bytes.  The list object will then be
-   populated with the first three return values above, and the memoryview object
+   populated with the first four return values above, and the memoryview object
    will be resized inplace to the size of the data and filled in with that data.
    The same list and memoryview objects can be reused in subsequent calls to
    this method, providing a way of receiving data without using the heap.
    For example::
 
         buf = bytearray(8)
-        lst = [0, 0, 0, memoryview(buf)]
+        lst = [0, 0, 0, 0, memoryview(buf)]
         # No heap memory is allocated in the following call
         can.recv(0, lst)
 
-.. method:: CAN.send(data, id, *, timeout=0, rtr=False)
+.. method:: CAN.send(data, id, *, timeout=0, rtr=False, extframe=False, fdf=False, brs=False)
 
    Send a message on the bus:
 
@@ -236,6 +267,13 @@ Methods
        a remote transmission request.  If *rtr* is True then only the length
        of *data* is used to fill in the DLC slot of the frame; the actual
        bytes in *data* are unused.
+     - *extframe* if True the frame will have an extended identifier (29 bits),
+       otherwise a standard identifier (11 bits) is used.
+     - *fdf* for CAN FD controllers, if set to True, the frame will have an FD
+       frame format, which supports data payloads up to 64 bytes.
+     - *brs* for CAN FD controllers, if set to True, the bitrate switching mode
+       is enabled, in which the data phase is transmitted at a differet bitrate.
+       See :meth:`CAN.init` for the data bit timing configuration parameters.
 
      If timeout is 0 the message is placed in a buffer in one of three hardware
      buffers and the method returns immediately. If all three buffers are in use
@@ -302,4 +340,10 @@ Constants
           CAN.LIST32
           CAN.MASK32
 
-   The operation mode of a filter used in :meth:`~CAN.setfilter()`.
+   The operation mode of a filter used in :meth:`~CAN.setfilter()` for classic CAN.
+
+.. data:: CAN.DUAL
+          CAN.RANGE
+          CAN.MASK
+
+   The operation mode of a filter used in :meth:`~CAN.setfilter()` for CAN FD.

docs/library/pyb.DAC.rst

@@ -49,7 +49,7 @@ To output a continuous sine-wave at 12-bit resolution::
 Constructors
 ------------
 
-.. class:: pyb.DAC(port, bits=8, *, buffering=None)
+.. class:: DAC(port, bits=8, *, buffering=None)
 
    Construct a new DAC object.
 
@@ -122,3 +122,15 @@ Methods
      dac2 = DAC(2)
      dac1.write_timed(buf1, pyb.Timer(6, freq=100), mode=DAC.CIRCULAR)
      dac2.write_timed(buf2, pyb.Timer(7, freq=200), mode=DAC.CIRCULAR)
+
+Constants
+---------
+
+.. data:: DAC.NORMAL
+
+   NORMAL mode does a single transmission of the waveform in the data buffer,
+
+.. data:: DAC.CIRCULAR
+
+   CIRCULAR mode does a transmission of the waveform in the data buffer, and wraps around
+   to the start of the data buffer every time it reaches the end of the table.

docs/library/pyb.ExtInt.rst

@@ -51,7 +51,7 @@ usrsw.h for an example of using this.
 Constructors
 ------------
 
-.. class:: pyb.ExtInt(pin, mode, pull, callback)
+.. class:: ExtInt(pin, mode, pull, callback)
 
    Create an ExtInt object:
 

docs/library/pyb.Flash.rst

@@ -15,7 +15,7 @@ application.
 Constructors
 ------------
 
-.. class:: pyb.Flash()
+.. class:: Flash()
 
    Create and return a block device that represents the flash device presented
    to the USB mass storage interface.
@@ -25,7 +25,7 @@ Constructors
 
    This constructor is deprecated and will be removed in a future version of MicroPython.
 
-.. class:: pyb.Flash(*, start=-1, len=-1)
+.. class:: Flash(*, start=-1, len=-1)
    :noindex:
 
    Create and return a block device that accesses the flash at the specified offset. The length defaults to the remaining size of the device.

docs/library/pyb.I2C.rst

@@ -56,7 +56,7 @@ Master also has other methods::
 Constructors
 ------------
 
-.. class:: pyb.I2C(bus, ...)
+.. class:: I2C(bus, ...)
 
    Construct an I2C object on the given bus.  ``bus`` can be 1 or 2, 'X' or
    'Y'. With no additional parameters, the I2C object is created but not
@@ -96,6 +96,10 @@ Methods
        that DMA transfers have more precise timing but currently do not handle bus
        errors properly)
 
+   The actual clock frequency may be lower than the requested frequency.
+   This is dependant on the platform hardware. The actual rate may be determined
+   by printing the I2C object.
+
 .. method:: I2C.is_ready(addr)
 
    Check if an I2C device responds to the given address.  Only valid when in controller mode.

docs/library/pyb.LCD.rst

@@ -41,7 +41,7 @@ For example, to make a bouncing dot, try::
 Constructors
 ------------
 
-.. class:: pyb.LCD(skin_position)
+.. class:: LCD(skin_position)
 
    Construct an LCD object in the given skin position.  ``skin_position`` can be 'X' or 'Y', and
    should match the position where the LCD pyskin is plugged in.

docs/library/pyb.LED.rst

@@ -10,7 +10,7 @@ The LED object controls an individual LED (Light Emitting Diode).
 Constructors
 ------------
 
-.. class:: pyb.LED(id)
+.. class:: LED(id)
 
    Create an LED object associated with the given LED:
 

docs/library/pyb.Pin.rst

@@ -58,23 +58,13 @@ an ordinal pin number:
 You can set ``pyb.Pin.debug(True)`` to get some debug information about
 how a particular object gets mapped to a pin.
 
-When a pin has the ``Pin.PULL_UP`` or ``Pin.PULL_DOWN`` pull-mode enabled,
-that pin has an effective 40k Ohm resistor pulling it to 3V3 or GND
-respectively (except pin Y5 which has 11k Ohm resistors).
-
-Now every time a falling edge is seen on the gpio pin, the callback will be
-executed. Caution: mechanical push buttons have "bounce" and pushing or
-releasing a switch will often generate multiple edges.
-See: http://www.eng.utah.edu/~cs5780/debouncing.pdf for a detailed
-explanation, along with various techniques for debouncing.
-
 All pin objects go through the pin mapper to come up with one of the
 gpio pins.
 
 Constructors
 ------------
 
-.. class:: pyb.Pin(id, ...)
+.. class:: Pin(id, ...)
 
    Create a new Pin object associated with the id.  If additional arguments are given,
    they are used to initialise the pin.  See :meth:`pin.init`.
@@ -98,7 +88,7 @@ Class methods
 Methods
 -------
 
-.. method:: Pin.init(mode, pull=Pin.PULL_NONE, \*, value=None, alt=-1)
+.. method:: Pin.init(mode, pull=Pin.PULL_NONE, *, value=None, alt=-1)
 
    Initialise the pin:
 
@@ -107,7 +97,8 @@ Methods
         - ``Pin.IN`` - configure the pin for input;
         - ``Pin.OUT_PP`` - configure the pin for output, with push-pull control;
         - ``Pin.OUT_OD`` - configure the pin for output, with open-drain control;
-        - ``Pin.AF_PP`` - configure the pin for alternate function, pull-pull;
+        - ``Pin.ALT`` - configure the pin for alternate function, input or output;
+        - ``Pin.AF_PP`` - configure the pin for alternate function, push-pull;
         - ``Pin.AF_OD`` - configure the pin for alternate function, open-drain;
         - ``Pin.ANALOG`` - configure the pin for analog.
 
@@ -117,10 +108,14 @@ Methods
         - ``Pin.PULL_UP`` - enable the pull-up resistor;
         - ``Pin.PULL_DOWN`` - enable the pull-down resistor.
 
+       When a pin has the ``Pin.PULL_UP`` or ``Pin.PULL_DOWN`` pull-mode enabled,
+       that pin has an effective 40k Ohm resistor pulling it to 3V3 or GND
+       respectively (except pin Y5 which has 11k Ohm resistors).
+
      - *value* if not None will set the port output value before enabling the pin.
 
-     - *alt* can be used when mode is ``Pin.AF_PP`` or ``Pin.AF_OD`` to set the
-       index or name of one of the alternate functions associated with a pin.
+     - *alt* can be used when mode is ``Pin.ALT`` , ``Pin.AF_PP`` or ``Pin.AF_OD`` to
+       set the index or name of one of the alternate functions associated with a pin.
        This arg was previously called *af* which can still be used if needed.
 
    Returns: ``None``.
@@ -183,6 +178,10 @@ Methods
 Constants
 ---------
 
+.. data:: Pin.ALT
+
+   initialise the pin to alternate-function mode for input or output
+
 .. data:: Pin.AF_OD
 
    initialise the pin to alternate-function mode with an open-drain drive
@@ -237,17 +236,17 @@ pin X3.
 For the pyboard, x3_af would contain:
     [Pin.AF1_TIM2, Pin.AF2_TIM5, Pin.AF3_TIM9, Pin.AF7_USART2]
 
-Normally, each peripheral would configure the af automatically, but sometimes
-the same function is available on multiple pins, and having more control
-is desired.
+Normally, each peripheral would configure the alternate function automatically,
+but sometimes the same function is available on multiple pins, and having more
+control is desired.
 
 To configure X3 to expose TIM2_CH3, you could use::
 
-   pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=pyb.Pin.AF1_TIM2)
+   pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.ALT, alt=pyb.Pin.AF1_TIM2)
 
 or::
 
-   pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=1)
+   pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.ALT, alt=1)
 
 Methods
 -------

docs/library/pyb.RTC.rst

@@ -17,7 +17,7 @@ Example usage::
 Constructors
 ------------
 
-.. class:: pyb.RTC()
+.. class:: RTC()
 
    Create an RTC object.