Mising documentation for uos.stat()
-
One of the LoPy issues is the really poor documentation. There are lot of information missing or if it looks like documented in fact unusable. Not the only one but I faced recently the explanation uos.stat() return values :(
Why the Hell I have to do reverse engineering to use a commercial product?
-
@robert-hh said in Mising documentation for uos.stat():
It is a commercial product range offered in form of development and OEM moduls.
-
@soren @bmarkus I see this as a semi-commercial product.
The documentation is not complete and sometimes wrong, since it was taken from the micropython.org port. Then some extension were made, but no-one seemed to have checked, whether everything fits. There seem to be a person now in Pycom.io dedicated to documentation, but maybe I'm wrong.
But if you like, you can contribute to the documentation. Sometimes, PRs to the documentation are noticed. In case of uos.stat(), the documentation is present.
-
Couldn't agree more.
-
@robert-hh
you have right but without doc you do not know what are that numbers in touple
you can guess but not for surebut as @sakis say it will change in this week
-
This is a Micro, fighting for every byte for memory. Too many features make it unusable.
-
@robert-hh said in Mising documentation for uos.stat():
The symbolic indices are NOT set.
and that is the point
-
No, not that way. os.stat() return a 10-tuple, and the 7th, os_stat()[6], is the size. The symbolic indices are NOT set.
-
@robert-hh said in Mising documentation for uos.stat():
it work for you in that way?
likeos.stat().ST_SIZE?i must check this at home - i tested this previously and i remember that it does not know ST_SIZE
-
The returned tuple has the structure defined for Python3 os.stat(). Only not all values are populated. useful values are:
ST_MODE
ST_SIZE
ST_ATIME which is teh same as ST_MTIME and ST_CTIME
The other values are set to zero, since they do not apply in the given environment, but the full structure is returned for compatibility.
No reason to complain. If there is not special documentation, assume Python compliance as a plausible choice.
-
Fair points. We are planning to release an update to our documentation this week and documenting the return values of
os.statwill be part of it.
-
@sakis said in Mising documentation for uos.stat():
About your rest points, I agree that a docs link should be added to pycom.io. And we are trying hard to improve both our documentation and our firmware.
After 21 days Pycom doc looks the same at https://docs.pycom.io/pycom_esp32/library/uos.html
saying only
Get the status of a file or directory.
So, question is still valid, what is the return value? It is a question related to your own commercial product, not related to chip vendor, LoRa Alliance, CIA, KGB, ...
What is about making a product usable for its customers and provide documentation? How do you expect to use it (expecting we get some free RAM and stable functions instead of changing it every week, introducing new bugs, etc.)?
-
@sakis
I see that you mention that you are not creator of micropython...
but in normal python os.stat return object
class os.stat_result
but here it returntouplewithout any description
e.g.:>>> os.stat('/sd') (16384, 0, 0, 0, 0, 0, 0, 12873600, 12873600, 12873600)what are that values?
i need to know how big is sd card, free space ...
-
The Pycom doc parts that refer to MicroPython are not modified to allow future merging. Here's the original MicroPython doc of
uos.stat: http://docs.micropython.org/en/latest/pyboard/library/uos.html#uos.stat. As you see, there's nothing there. That's what I meant by standard MicroPython documentation. Perhaps we should improve the documentation of that function in our docs.Without being the creator of MicroPython, I think that the fact that it is a port of Python 3 for microcontrollers means that the error codes of a function like
statmust be the same (or at least close) to the error codes of standard Python. That's why I referred to Python's documentation.About your rest points, I agree that a docs link should be added to pycom.io. And we are trying hard to improve both our documentation and our firmware.
Sorry to hear about your disappointment. I hope that we can change your mind.
-
@sakis said in Mising documentation for uos.stat():
Hello,
This is standard micropython documentation and the returned values are actually documented in standard Python: https://docs.python.org/2/library/errno.html#module-errno
Does that help?
Why are you referring to the error codes?
In the Pycom doc there is nothing about return values. Without describing return values for a function it is not a documentation. You can say 'It is the same as in cPython' but even in this case why to refer to an external documention in your own doc?
As a developer, do you like to work with a product with useless documentation, unmet commitments, misleading brochures and product descriptions with missing features based on unstable beta hardware where even no any warranty that hw vendor will fix issues and no ETA it will ever work on acceptable level?
As a hobby DIY constructor you can play with such board in the evening in your free time but no way to use it for a product.You can say it is up to the hw vendor which is probably true. But to release a product based on alpha unproven silicon with alpha fw is a bad decision op Pycom. During the last few month your documentation structure is still messy and nearly unusable. Yesterday I was looking for the documentation and at pycom.io site there are no single menu item for docs. You do not have to reinvent the wheel, just do what others are doing well. Not referring to big guns, but other KickStarters with similar products providing excellent docs.
I'm really unhappy and fior sure will never buy any Pycom product and do not advice others to do it.
-
Hello,
This is standard micropython documentation and the returned values are actually documented in standard Python: https://docs.python.org/2/library/errno.html#module-errno
Does that help?
