docs/library: Add description of "index" parameter to uos.dupterm(). #3144
Conversation
|
Looks good, but I'm not sure about these negative indexes - what benefit do they give? They sound both as a complication and confusing. |
The idea is to make it a bit cleaner when a port provides default REPL source, plus a few extra dupterm slots for the user. With the requirement that slot 0 being always available for the user the 2 options are either to allow negative indices: compared to not having negative indices: Having negative indices for default/built-in slots, and >=0 indices for free/user slots seems slightly cleaner to me. (Of course, the user can still change the negative slots.) It's not such a big issues, the default/built-in slots will anyway need to be documented per port, so if they live at -1 or +1 is not so important. |
|
See also #1736 for some previous discussion on non-blocking, and push vs pull, behaviour of dupterm/REPL. In the docs written here I followed the existing implementations (which are polling based) and wrote that streams should be in non-blocking mode. An alternative is to require the stream to implement ioctl (at the C and/or Python level) and work with select.ipoll, so that the REPL can do polling this way. |
|
@dpgeorge plans to implement what is written in the uos.dupterm TODO?
|
Yes, that will be worked on soon. |
|
Ok, let's go for non-negative indices only (ie index=0, 1, 2, ...). Looking from afar it is simpler that way, a given port will then have N slots available, from 0...N-1, and some may be pre-populated with the default REPL source. |
|
Well, I'll let you decide on that. It's just from cursory look, it's a bit confusing, though beyond that, the general idea is clear: to partition set of slots into "system" (negative indexes) and "user" (non-negative), If you think that's the right way to do it, go for it. |
I'd say this point isn't yet decided, as dupterm implementation is "highly experimental" (even with these changes). |
Dupterm has been working pretty well for a while now. And one of the aims of this PR is so that #1736 can be closed after this one has been merged, since then dupterm will be well specified and also working (on more than one port). |
|
But not on unix, and that's the primary port. |
In my books stmhal is the primary port. Unix can stay unsupported in this regard, otherwise I spend time on things that don't matter. |
|
@dpgeorge : Let's have this patch merged. Somehow I still find negative indexes non-natural though. E.g., if I saw uos.dupterm(stream, -1), I might as well think "1st slot from the end". |
779b34d to
e30ba2f
Compare
Yes I agree. So I removed that sentence in the docs, and added a clarification that the index is a non-negative integer. Now merged. |
Following on from #2891 (and previous discussions on dupterm) this is a proposal to extend uos.dupterm() behaviour to support multiple slots.
Current behaviour is slightly modified: currently uos.dupterm() with no args will return the current stream object. But with an additional (optional) argument to specify the index, this becomes messy. So the proposal is to remove this "getter" behaviour and instead return the previous stream object when a new one is set, ie:
Also, the proposal is to use negative indices to indicate slots that are configured by default (if a port has multiple slots). So stmhal would have USB_VCP at index=-1, and indices 0, 1, 2, ... (up to some max, which could be dynamic depending if the slot is ever referenced) are for the user to configure (the user can also access the negative slot, to disable USB_VCP). And esp8266 could have UART0 at index=-1 and then webrepl goes on index=0 (and it would have just 2 solts).