Why are these BTLE low-level constants defined as 'Incomplete'?

[brianreinhold]

In the low-level bluetooth library the central.pyi file defines these constants as follows:

_ADV_TYPE_FLAGS: Incomplete
_ADV_TYPE_NAME: Incomplete
_ADV_TYPE_UUID16_COMPLETE: Incomplete
_ADV_TYPE_UUID32_COMPLETE: Incomplete
_ADV_TYPE_UUID128_COMPLETE: Incomplete
_ADV_TYPE_UUID16_MORE: Incomplete
_ADV_TYPE_UUID32_MORE: Incomplete
_ADV_TYPE_UUID128_MORE: Incomplete
_ADV_TYPE_APPEARANCE: Incomplete
_ADV_TYPE_MANUFACTURER: Incomplete

Why 'Incomplete'? These constants have known values defined by the BT_SIG Bluetooth standards. There must be a reason for NOT providing the actual values and saving the implementer the effort of searching the standards to find them. Can anyone explain the rationale for 'Incomplete'?

Thanks

[andrewleech]

Where is the central.pyi you refer to from?

[brianreinhold]

It must be part of the micropython library installed on the PICO. Visual Studio code shows a whole bunch of pyi files defining the interfaces for the modules in the library. I don't see any source. In my very C-biased life they remind me of h-files. When I use the IDE to search and find definitions, that's where it tends to go.

[Josverl]

Python stubfiles serve a different purpose to the language compared to C header files.
but both of them can be used to lookup things, by IDEs and tools and humans alike.
The micropython ones are 'stub-only distributions' they can/are distributed separately from the python (compiled) code that is part of the firmware on your Pico-W.

See : https://typing.readthedocs.io/en/latest/source/stubs.html

[Josverl]

Hello Brian,
I assume that you are referring to a stub file from the micropython-*-stubs and that you are referring to a v1.20.0 version of the stubs.
Its fine to discus here , but actually they are not created or maintained by the micropython maintainers , but by me , leveraging the documentation and the combination some custom models and introspection.

My motto for the stubs and micropython-stubber is: 'To make it not wrong, and improve from there.'
The result of that is quite decent, if I may say so myself, but not perfect by far.

As part of creating the stubs the python modules that are normally frozen into the firmware are transformed into stubs using the mypy.stubgen tool
This remove any of the constants as a rule , and if it cant figure out the type - it uses Incomplete as the type. it should have used int in these cases.

two points to note here:

1. not having the the values in stub files is the recommended way , although I have been tempted to code up a solution to add them. but 99% of stubs do not have values.
2. I think mypy stubgen gets thrown off by const foo = const(4) as during generation of the stubs it cannot from micropython import const.
   That is something that I can try to make work, either using mypy.stubgen or pyright

What I still would like to understand is why you want/need to know the values of the defined constants. the purpose of these is that you do not need to know the actual value?

Can you confirm if you have indeed installed the stubs , or are using a tool such as MicroPico ( which includes them )

[brianreinhold]

The pyi files I am referring to are shown by Visual Studio Code after installation of Micropython on the PICO W. I am no expert on Python (very C biased in the Bluetooth world and am not used to dynamically typed languages) and I could not even think of being able to do what you have done. I am having a hard time following the examples because nothing is typed so I cannot very easily explore what various fields and objects are. I do global searches and try to find matches and work backwards. I am slowly but surely back-typing the client example to try and understand what the library APIs provide and do. Once I type a variable VS Code's pylance becomes very helpful!

I just thought it was funny that a set of constants defined by the BT SIG standards where typed as Incomplete. There is likely a good reason for that but my ignorance of Python (especially creating non-source libraries) put me at a loss. If one entered the actual constant values

_ADV_TYPE_FLAGS: int = 0x02

in the pyi files, would that cause a catastrophe?

[Josverl]

Do you have the MicroPico add-in installed in VSCode ?

in the pyi files, would that cause a catastrophe?

No but it would violate the recommendation , slow down all linters and static typecheckers.
Also someone would need to manually maintain it or update mypy.creatstubs to emit the values.

I'm happy to put it on the backlog , but ill prioritize on fixing some of the other stuff that is not yet not wrong.
501 and 502
I'm happy if you would like to help out

[brianreinhold]

MY Python knowledge is magnitudes below your competence and I would not even begin to know how to do what you are doing. I will check out the MP add in (in case I do not have it) and maybe its best to get the Micropython source - at least for Bluetooth!

Oh, that plugin is now called the MicroPico extension and that I do have. I do have all the other extensions for normal Python. I see a lot of other extensions for micropython but they are all full of CHinese characters so I don't think they would be of much use for me.

[Josverl]

NP , I'm happy you reported what you found.
That in itself is help already.

/Jos