v3/README.md: Remove V2 porting guide.

Author: peterhinch

v3/README.md

@@ -1,9 +1,9 @@
 # 1. Guide to uasyncio V3
 
-The new release of `uasyncio` is pre-installed in current daily firmware 
-builds and will be found in release builds starting with V1.13. This complete
-rewrite of `uasyncio` supports CPython 3.8 syntax. A design aim is that it
-should be be a compatible subset of `asyncio`.
+This release of `uasyncio` is pre-installed on all platforms except severely
+constrained ones such as the 1MB ESP8266. This rewrite of `uasyncio` supports
+CPython 3.8 syntax. A design aim is that it should be be a compatible subset of
+`asyncio`. The current version is 3.0.0.
 
 These notes and the tutorial should be read in conjunction with
 [the official docs](http://docs.micropython.org/en/latest/library/uasyncio.html)
@@ -12,7 +12,10 @@ These notes and the tutorial should be read in conjunction with
 
 This repo contains the following:
 
-### [V3 Tutorial](./docs/TUTORIAL.md)  
+### [V3 Tutorial](./docs/TUTORIAL.md)
+
+Intended for users with all levels of experience with asynchronous programming.
+
 ### Test/demo scripts  
 
 Documented in the tutorial.
@@ -46,6 +49,11 @@ useful in their own right:
  * [HD44780](./docs/hd44780.md) Driver for common character based LCD displays
  based on the Hitachi HD44780 controller.
 
+### Event-based programming
+
+[A guide](./docs/EVENTS.md) to a writing applications and device drivers which
+largely does away with callbacks.
+
 ### A monitor
 
 This [monitor](https://github.com/peterhinch/micropython-monitor) enables a
@@ -98,9 +106,8 @@ will be addressed in due course.
 ### 2.1.1 Fast I/O scheduling
 
 There is currently no support for this: I/O is scheduled in round robin fashion
-with other tasks. There are situations where this is too slow, for example in
-I2S applications and ones involving multiple fast I/O streams, e.g. from UARTs.
-In these applications there is still a use case for the `fast_io` V2 variant.
+with other tasks. There are situations where this is too slow and the scheduler
+should be able to poll I/O whenever it gains control.
 
 ### 2.1.2 Synchronisation primitives
 
@@ -109,106 +116,3 @@ These CPython primitives are outstanding:
  * `BoundedSemaphore`.
  * `Condition`.
  * `Queue`.
-
-# 3. Porting applications from V2
-
-Many applications using the coding style advocated in the V2 tutorial will work
-unchanged. However there are changes, firstly to `uasyncio` itself and secondly
-to modules in this repository.
-
-## 3.1 Changes to uasyncio
-
-### 3.1.1 Syntax changes
-
- * Task cancellation: `cancel` is now a method of a `Task` instance.
- * Event loop methods: `call_at`, `call_later`, `call_later_ms`  and
- `call_soon` are no longer supported. In CPython docs these are
- [lightly deprecated](https://docs.python.org/3/library/asyncio-eventloop.html#preface)
- in application code; there are simple workrounds.
- * `yield` in coroutines must be replaced by `await asyncio.sleep_ms(0)`:
- this is in accord with CPython where `yield` will produce a syntax error.
- * Awaitable classes. The `__iter__` method works but `yield` must be replaced
- by `await asyncio.sleep_ms(0)`.
-
-It is possible to write an awaitable class with code portable between
-MicroPython and CPython 3.8. This is discussed
-[in the tutorial](./docs/TUTORIAL.md#412-portable-code).
-
-### 3.1.2 Change to stream I/O
-
-Classes based on `uio.IOBase` will need changes to the `write` method. See
-[tutorial](./docs/TUTORIAL.md#64-writing-streaming-device-drivers).
-
-### 3.1.3 Early task creation
-
-It is [bad practice](https://github.com/micropython/micropython/issues/6174)
-to create tasks before issuing `asyncio.run()`. CPython 3.8 throws if you do.
-Such code can be ported by wrapping functions that create tasks in a
-coroutine as below.
-
-There is a subtlety affecting code that creates tasks early:
-`loop.run_forever()` did just that, never returning and scheduling all created
-tasks. By contrast `asyncio.run(coro())` terminates when the coro does. Typical
-firmware applications run forever so the coroutine started by `.run()` must
-`await` a continuously running task. This may imply exposing an asynchronous
-method which runs forever:
-
-```python
-async def main():
-   obj = MyObject()  # Constructor creates tasks
-   await obj.run_forever()  # Never terminates
-
-def run():  # Entry point
-    try:
-        asyncio.run(main())
-    finally:
-        asyncio.new_event_loop()
-```
-
-## 3.2 Modules from this repository
-
-Modules `asyn.py` and `aswitch.py` are deprecated for V3 applications. See
-[the tutorial](./docs/TUTORIAL.md#3-synchronisation) for V3 replacements which
-are more RAM-efficient.
-
-### 3.2.1 Synchronisation primitives
-
-These were formerly provided in `asyn.py` and may now be found in the
-`primitives` directory, along with additional unofficial primitives.
-
-The CPython `asyncio` library supports these synchronisation primitives:
- * `Lock` - already incorporated in new `uasyncio`.
- * `Event` - already incorporated.
- * `gather` - already incorporated.
- * `Semaphore` and `BoundedSemaphore`. In this repository.
- * `Condition`. In this repository.
- * `Queue`. In this repository.
-
-The above unofficial primitives are CPython compatible. Using future official
-versions will require a change to the import statement only.
-
-### 3.2.2 Synchronisation primitives (old asyn.py)
-
-Applications using `asyn.py` should no longer import that module. Equivalent
-functionality may now be found in the `primitives` directory: this is
-implemented as a Python package enabling RAM savings. The new versions are also
-more efficient, replacing polling with the new `Event` class.
-
-These features in `asyn.py` were workrounds for bugs in V2 and should not be
-used with V3:
- * The cancellation decorators and classes (cancellation works as per CPython).
- * The nonstandard support for `gather` (now properly supported).
-
-The `Event` class in `asyn.py` is now replaced by `Message` - this is discussed
-in [the tutorial](./docs/TUTORIAL.md#36-message).
-
-### 3.2.3 Switches, Pushbuttons and delays (old aswitch.py)
-
-Applications using `aswitch.py` should no longer import that module. Equivalent
-functionality may now be found in the `primitives` directory: this is
-implemented as a Python package enabling RAM savings.
-
-New versions are provided in this repository. Classes:
- * `Delay_ms` Software retriggerable monostable (watchdog-like object).
- * `Switch` Debounced switch with close and open callbacks.
- * `Pushbutton` Pushbutton with double-click and long press callbacks.

v3/docs/TUTORIAL.md

@@ -2,7 +2,8 @@
 
 This tutorial is intended for users having varying levels of experience with
 asyncio and includes a section for complete beginners. It is for use with the
-new version of `uasyncio`, currently V3.0.0.
+new version of `uasyncio`, currently V3.0.0. See [this overview](../README.md)
+for a summary of documents and resources for `uasyncio`.
 
 Most code samples are now complete scripts which can be cut and pasted at the
 REPL.