RFC: Finalized network API

[pfalcon]

There were a number (sometimes inconsistent) proposals for extending the existing (not formally speced) network module API. My usual response was: "please come up with a generic RFC of a flexible, extensible network API". Nobody picked up that task, so finally I'm getting to it.

The ideas: the spec should be in the docs, and independent of any particular implementation. Coincidentally, network.rst is the most conditionalized .rst file in the docs. And we can't just clamp everything into a single description, because network setup is an important topic and there always will be per-device peculiarities.

So, the proposal: network.rst starts with a description of a generic API or "base class", say BaseNIC, where generic .connect(), .config(), etc. described. Followed by sections on individial network classes. Ideally, these sections will be deconditionalized and all present at once, though I'm not sure how easy it will be to achieve that due to naming conflict.

[dpgeorge]

network.rst starts with a description of a generic API or "base class", say BaseNIC, where generic .connect(), .config(), etc. described. Followed by sections on individial network classes.

Sounds ok to me, at least for initial attempt. Individual network drivers may need to have separate sub-docs if they get too complex (eg network.esp8266.rst, network.cc3100.rst, etc).

[pfalcon]

I posted what I wrote in one session as https://github.com/micropython/micropython/pull/3017 , not sure when I'll be able to continue.

[dpgeorge]

See #3351 for a proposal to enhance AbstractNIC.status() to query general status values.

[dpgeorge]

The network API is pretty stable now. This can be closed.