search

bbcmicrobit / micropython

Port of MicroPython for the BBC micro:bit
https://microbit-micropython.readthedocs.io
Other
603 stars 284 forks source link

readall method does not exist #591

Closed DavidWhaleMEF closed 5 years ago

DavidWhaleMEF commented 5 years ago

The currently published readthedocs for the uart module refer to a 'readall' method.

https://microbit-micropython.readthedocs.io/en/latest/uart.html

screen shot 2018-10-30 at 12 55 17

The current v1.0.0 MicroPython image does not have this method:

MicroPython v1.9.2-34-gd64154c73 on 2017-09-01; micro:bit v1.0.0 with nRF51822
Type "help()" for more information.
>>> dir(uart)
['init', 'any', 'read', 'readline', 'readinto', 'write', 'ODD', 'EVEN']
DavidWhaleMEF commented 5 years ago

Note, it looks like this functionality can be achieved with readinto(), the main difference being that you provide the buffer, rather than having the buffer created for you (as the old readall did).

I recall reading that @dpgeorge had removed this a while ago, but it's still in the live docs, and the live docs don't match the live language (I appreciate we're all working to correct that at the moment though!)

DavidWhaleMEF commented 5 years ago

Note: Removing methods will break existing users code. We all know that, but its worth remembering that, as it provides a bad experience for users who expect their code to always work on the latest editors and languages.

Should we mark removed methods in the docs as 'deprecated, please use x instead', and have a deprecation process a bit like Java, where one major release marks it as deprecated, the next major release actually removes it?

And any method that once existed that is now deprecated and removed should be listed at the base of the readthedocs page for that method, so that users that miss the deprecation steps can still work out themselves what has gone wrong (and don't think 'how did this code ever work, like I just did??!!)

Comments welcomed @carlosperate @jaustin

P.S. I am developing a demo at the moment that heavily uses the uart, so I'm usefully experiencing and flushing these things out first hand!

microbit-carlos commented 5 years ago

Completely agree that we should have a good deprecation process, although the aim is to never have to use it.

The readall method was removed in https://github.com/bbcmicrobit/micropython/commit/d231463dd9a4c9fe366314c2a59d5ff507a22893, which was over 2 years ago. At this point I think we should add a note to the uart docs to indicate it has been deprecated. I've created this PR, let me know what you think: https://github.com/bbcmicrobit/micropython/pull/595

As far as achieving the same functionality goes, you can use the read() method without any arguments to do the same. PR https://github.com/bbcmicrobit/micropython/pull/588 clarifies the method behaviour if an argument is not provided.

microbit-carlos commented 5 years ago

Thanks David, the docs have been updated in PR #595.