Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
6 tasks
dlech opened this issue Jul 7, 2021 · 2 comments
Closed
6 tasks

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

dlech opened this issue Jul 7, 2021 · 2 comments
Labels
py-core Relates to py/ directory in source

Comments

@dlech
Copy link
Contributor

dlech commented Jul 7, 2021

Most MicroPython modules that implement subsets of standard Python modules start with "u". There are a few that still don't follow this pattern:

  • builtins
  • gc
  • cmath
  • math
  • _thread
  • termios

It would be nice to change these as well. My motivation is to be able to use Python tools (like code completion in an IDE) with MicroPython. Many of these tools require actually importing modules, so it breaks things if we have module that have the same name as standard library modules.

Any objections? Did I miss any?

@jimmo
Copy link
Member

jimmo commented Jul 7, 2021

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)
  1. 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?

@dlech
Copy link
Contributor Author

dlech commented Jul 7, 2021

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.

@dpgeorge dpgeorge added the py-core Relates to py/ directory in source label Mar 30, 2022
dlech added a commit to dlech/micropython that referenced this issue Jul 1, 2022
Most MicroPython modules with the same name as a Python standard library
module have the "u" prefix. This changes `math` and `cmath` to to
follow this pattern.

Issue: micropython#7499
Signed-off-by: David Lechner <david@pybricks.com>
dlech added a commit to dlech/micropython that referenced this issue Jul 1, 2022
Most MicroPython modules with the same name as a Python standard library
module have the "u" prefix. This changes `math` and `cmath` to to
follow this pattern.

Issue: micropython#7499
Signed-off-by: David Lechner <david@pybricks.com>
dlech added a commit to dlech/micropython that referenced this issue Jul 1, 2022
Most MicroPython modules with the same name as a Python standard library
module have the "u" prefix. This changes `math` and `cmath` to to
follow this pattern.

Issue: micropython#7499
Signed-off-by: David Lechner <david@pybricks.com>
dlech added a commit to dlech/micropython that referenced this issue Jul 1, 2022
Most MicroPython modules with the same name as a Python standard library
module have the "u" prefix. This changes `math` and `cmath` to to
follow this pattern.

Issue: micropython#7499
Signed-off-by: David Lechner <david@pybricks.com>
Wind-stormger pushed a commit to BPI-STEAM/micropython that referenced this issue Jan 30, 2023
Use composite action for fetching submodules
@dlech dlech closed this as completed Oct 7, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
py-core Relates to py/ directory in source
Projects
None yet
Development

No branches or pull requests

3 participants