Add "u" prefix to remaining standard modules? #7499

Activity

1. jimmo commented on Jul 7, 2021

   

   jimmo

   on Jul 7, 2021

   Member

   More actions

   Thanks @dlech -- I am in favour of this, but I think it would be first really good to define exactly the rules for naming (and documenting) modules.

   Some relevant history in #6164 (sys -> usys) and #4370 (array -> uarray). Note that not all ports have weak links, so this would technically be a breaking change on those ports, but this wasn't considered a blocker for usys.

   I know @dlech knows all this but just for completeness for anyone else reading this, the "u" prefix achieves two related but independent things:

   1. It signals that this is a MIcroPython library, which might mean any combination of:

   • It contains a subset of a Python standard library (e.g. ujson, uos)
   • It contains extra features relative to a Python standard library (e.g. uctypes, uos)
   • It's a built-in MicroPython-specific library (umachine, ubluetooth, etc)
   • It's a Python library that's "designed for MicroPython" (urequests, uasyncio)

   2. It allows the weak-links mechanism to work. i.e. a user can write import foo, in which case they'll get foo.py first, followed by built-in ufoo. Importantly, foo.py can start with from ufoo import *. This allows you to "fill in the gaps" with Python (urandom and micropython-lib's random are a good example). (It's called weak links because of how this used to work with aliases, but now it's been simplified to just stripping the u prefix when doing built-in lookup).

   I think builtins, gc, math, and cmath are all good candidates to be renamed. In order to make weak links work, _thread would have to become u_thread which is a bit weird, but probably fine? Note that there's already _uasyncio.

   In terms of other Python standard libraries that MicroPython implements, the only other one that springs to mind is on the Unix port we also have termios.

   We should aim to clear up the non-standard built-in libraries too, but that can be discussed in a separate issue. (i.e. should network be unetwork, like ubluetooth ?) (Also the non-built-in (or frozen) libraries... should we enable some form of weak links so that import asyncio works for frozen uasyncio?)

   The other thing I'd like to address is documentation. I would imagine that most users don't care about the u prefix, and arguably shouldn't know about it -- on all the main ports we enable weak links, so (I think?) we should be encouraging everyone to always write import foo (and almost never the try foo / except ufoo pattern). In which case should we consider documenting everything without the u prefix?
2. dlech commented on Jul 7, 2021

   

   dlech

   on Jul 7, 2021

   Last edited by dlech

   SponsorContributorAuthor

   More actions

   In order to make weak links work, _thread would have to become u_thread which is a bit weird, but probably fine?

   It does look a little weird, but I think it is better than having a special case for weak links.

   we should be encouraging everyone to always write import foo (and almost never the try foo / except ufoo pattern).

   I actually favor the opposite. This stems from the case where micropython-lib is also installed. For many modules, import foo would import the micropython-lib extensions, but if none of the extra functions are needed, then it is wasting time and RAM and significantly increasing the startup time of the program (which is a big deal in robotics competitions). So my rule of thumb is import ufoo unless you need the extra functionality.

   Also, considering the case of IDE tooling, always using import ufoo (where foo is a standard library module) lets you use existing linting and intellesense tools that take into consideration MicroPython differences without breaking the tools themselves. So I feel like that is another case to make ufoo the preferred usage.

   In the case where people want to write code that runs on both MicroPython and standard Python, then enabling weak links and just importing foo makes sense.
3. dpgeorge

   added

   py-coreRelates to py/ directory in sourceRelates to py/ directory in source

   on Mar 30, 2022
4. Wind-stormger

   added a commit that references this issue on Jan 30, 2023

   Merge pull request micropython#7499 from MicroDev1/ci

   ...

   cc822e0
5. dlech

   closed this as completedon Oct 7, 2023