Is there an official or well-known minimum interface standard for a list?

Question

I continue to see functions and documentation, such as this and this (to name a few), that work on or reference objects that look like a list.

I understand perfectly what the actual list is ( dir(list) ), and it can deduce which (often changing) methods from the list are needed in most references to a “list-like object”, however the number of times I see that it refers, left me with the following question:

Is there a standard or minimum minimum interface for a standard minimum interface? Is it as simple as updating __getitem__ , or agree that additional things like __len__ and __setitem__ also needed?

This may seem like semantics, but I can't help but think that if there is no standard minimum interface requirement, various ideas of "list similarity" may cause some problems / incorrect processing. Maybe this is just a minor flaw in writing duck Python?

Answer 1

See the collections.abc module. Of the abstract base classes listed there, list in Python implements Iterable , Container , Sized , Sequence and MutableSequence . Now of these, Iterable , Sequence and MutableSequence could be accidentally called list-like.

However, I would understand that the term list-like means that it is MutableSequence - it has at least the __getitem__ , __setitem__ , __delitem__ and __len__ , expecting it to also have the mixin methods mentioned in the documentation, such as append .

If there is no need for __setitem__ and __delitem__ , then you should call the sequence instead - the assumption is that if something accepts the sequence, it should not be mutable, thus str , bytes , tuple , etc. also work there.

---

Your two links emphasize the term's ambiguity:

The plotly API requires list-like objects to be serialized into a JSON array by the internal PlotlyJSONEncoder , which delegates most of the Python coding to JSONEncoder . However, the latter encodes only tuple and list (and subclasses) to the JSON array; thus, a list , a tuple or subclasses is used here. A custom sequence object that is not a subclass will result in a TypeError: [...] is not JSON serializable .

The unzip recipe you are associated with requires an object that behaves like a Sequence (volatility is not required), so tuple or str , or any custom object that implements Sequence , will do there.

---

TL; DR list-like is an undefined term. Instead, it is preferable to use the terms iterative, sequence and mutable sequence, now that they are defined in collections.abc .

Answer 2

The technical term for a list-like object is sequence . At least it supports ordering (that is, two objects with the same elements, but different orders are not equal), indexing ( foo[bar] such that bar is an integer less than the length of the sequence) and validation check ( in ) and has set length. It should support iteration, but if not, then Python will mimic it using indexing.

Answer 3

At almost any time you see an "-like object" in the Python documentation, the author is deliberately vague. The author decided that listing all the required interfaces would be too complicated, and only said that some of its interfaces are required. An object that implements all interfaces is guaranteed to work, but in most cases it will work with an object that implements much less.

With an "object-like list", probably the best thing you can do, with the exception of checking the source code, is to determine if it needs any of the mutable interfaces. If he needs only read-only access to the list, you can be sure that you do not need to perform any operations with a variable sequence.

If it says “list-like object or iterator”, you can provide something that implements a much simpler iterator interface.