uarray.array methods

[hlovatt]

Hi,

The documentation for `uarray.array` lists methods `append` and `extend`, however:

1. `dir(uarray.array)` gives: `['__class__', '__name__', 'append', 'extend', '__bases__', '__dict__', 'decode']`, what's
   `decode` (it appears to convert to a str - presumably same a `bytes` method of same name)?
2. Set and get indexing works but not delete, this implies `__getitem__` and `__setitem__`?

Therefore should the documentation include `decode`, `__getitem__`, and `__setitem__`?

Cheers,

Howard.

[hlovatt]

Playing with this in the REPL I have noticed some anomalies (where `a` is a `uarray.array`):

1. `a[0]` works but `a.__getitem__(0)` doesn't (it works in Python).
2. Similarly `a.__setitem__(0, x)`.
3. CPython's `array.array` doesn't have `decode`, instead it has `tobytes`.

So:

1. How can the indexing by documented?
2. Should decode be lodged as a bug, to be renamed `tobytes`? (`tobytes` doesn't have arguments unlike `decode` and the differences between CP and MP section of the documentation doesn't not this difference. The CP/MP differences doc only lists that `__contains__` is missing - there are many things missing!)

[hlovatt]

Also `__len__` is missing but `len(a)` works!

[hlovatt]

More:

1. `__add__` not present, but `a + a` works.
2. `__iadd__` not present, but `a += a` works.
3. `__repr__` not present, but `str(a)` and `repr(a)` both work.

[pythoncoder]

You'll find this applies to a lot of other data types too. Where a data type is defined in C, the Python magic (dunder) methods aren't always implemented. I think this is one of the "micro" aspects of the language. For example, try dir({}) in CPython and MicroPython.

[hlovatt]

Thanks.

I guess my best bet is to add the dunder (magic) methods and in the documentation and note that the actual method isn't present and hence can't be directly called but the builtins do work. EG for `uarray.array`:

Code: Select all

def __getitem__(self, index: int) -> Any:
	"""
	Returns the item at the given index; negative indices count from end and `IndexError`is thrown 
	if the index out of range.
	**Note**: The method `__getitem__` cannot be called directly (`a.__getitem__(i)` fails) and the 
	method is not present in `__dict__`, however `a[i]` does work.
	"""

Thoughts?

[stijn]

Depends, why do you need the magic methods?

[hlovatt]

To document what the class does (subset of Python array.array) and also for a type shed for IDEs so they know what the class can do.

[stijn]

Ok but the if you look at the Python standard library documentation, the basic documentation also doesn't list all magic methods separately for each type. See e.g. https://docs.python.org/3.8/library/stdtypes.html#dict: it doesn't talk about __getitem__ but just uses d[key] and the documentation of special methods is a separate section at https://docs.python.org/3/reference/datamodel.html. Maybe not a bad idea to follow that convention for MicroPython documentation projects - at least from a user's point of view, I assume most people looking for information on what a class can do would be interested in knowing d[key] works rather than whether that is implemented using __getitem__, which only comes into play for specific customisation purposes for instance.

Wrt typesheds, that's something else, but depends on what information the IDE needs I guess? E.g. when you use d[key] in an IDE, how is it going to figure out whether that works? By looking at the existence of __getitem__?

[hlovatt]

Not sure what all the IDEs do; but PyCharm recognises the dunder methods as both documentation, for warnings, and for types when using the operators.