43

I keep seeing functions and documentation like this and this (to name a few) which operate on or refer to list-like objects.

I'm quite aware of what exactly an actual list is (dir(list)), and can deduce what (often varying) methods from a list are necessary in most references to a "list-like object", however the number of times I see it referenced has left me with the following question:

Is there an official or common knowledge standard minimal interface for a "list-like" object? Is it as simple as actualizing__getitem__, or is it agreed that additional things like __len__ and __setitem__are required as well?

This may seem like semantics, but I can't help but think that if there does not exist a standard minimal interface requirement, various ideas of "list-likeness" could cause some issues/improper handling. Perhaps this is just a slight downside to Python's duck typing?

6
  • possible duplicate of Comprehensive list of Python protocols/interfaces
    – aruisdante
    Commented Mar 3, 2015 at 20:59
  • 14
    Welcome to the wonderful world of duck typing.
    – user1804599
    Commented Mar 3, 2015 at 21:21
  • 3
    @aruisdante Those are some pretty poor link-only answers that do not address the OP's question.
    – ohmu
    Commented Mar 3, 2015 at 23:16
  • 1
    @cpburnz While they're definitely link only, and not the highest quality in terms of explaining the link, I'm not really sure how you don't provide a comprehensive list of standard python protocols (which being list-like obstinately is, hence the suggested duplicate), without linking to them, especially since the links are to the core python doc. SO certainly wouldn't be the proper place for such a repository. Having said that, Antii's answer certainly covers the specific case, hence why I upvoted it.
    – aruisdante
    Commented Mar 3, 2015 at 23:21
  • 3
    @aruisdante References are great, but simply linking to them is not good enough for a stackoverflow answer. A summary of the information should be provided. Also, the data model documentation is a very dense read. Without already having an understanding of how things work, it's not very clear which methods go with which protocol.
    – ohmu
    Commented Mar 3, 2015 at 23:30

3 Answers 3

42

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 casually called list-like.

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

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


Your two links highlight the vagueness of the term:

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

The unzip recipe you linked to requires an object that behaves like a Sequence, (mutability is not required), thus a tuple or str, or any custom object implementing Sequence will do there.


TL;DR list-like is a vague term. It is preferable to use the terms iterable, sequence and mutable sequence instead, now that these are defined in collections.abc.

3
  • This clears up a lot. So although there is no "standard" minimal definition (answers my main question), you're saying it probably should (or is possibly generally accepted) to refer to a MutableSequence? Commented Mar 3, 2015 at 21:48
  • 2
    Or even better that call things Iterable, Sequence, MutableSequence or list instead of something as vague as list-like Commented Mar 3, 2015 at 21:49
  • 1
    Cheers. Poor terminology as a whole I suppose. Thanks! Commented Mar 4, 2015 at 11:33
11

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

9
  • 5
    I think "mutable sequence" would be more accurate. A tuple for example is a sequence, but it does not support item assignment (__setitem__) like a list does. If a function is documented to take a list-like object, it could very well intend to mutate that object.
    – user2555451
    Commented Mar 3, 2015 at 21:12
  • 2
    @iCodez: We will agree to disagree. I personally feel that modifying mutable arguments is pathological behavior, since there's no guarantee (beyond the documentation, of course) that the argument will be mutable in the first place. Commented Mar 3, 2015 at 21:13
  • 4
    The python data model pretty specifically states that a list is a mutable sequence. Any API specifying a list-like will almost certainly expect mutablilty, otherwise it would (or at least should) use a different term. The goodness/badness of parameters that are used as both input and output is not really part of the scope of the python data model. In addition, the API might be specifying it returns a list-like, in which case the point about modifying inputs is moot.
    – aruisdante
    Commented Mar 3, 2015 at 21:26
  • 2
    @aruisdante If you have citations for these claims, you should post them as an answer.
    – Random832
    Commented Mar 3, 2015 at 22:02
  • 1
    It's not clear at all that this is meant to be a contract. In particular, terms like "some" sequences (support extended slicing) suggest it's meant to be descriptive. Now, list does support extended slicing, but it's no more clear that "list-like" requires this than support for its other methods (or, for that matter, isinstance(..., list)). I'm also interested to know how append is not part of being a mutable sequence: "Mutable sequences should provide methods append(), count(), index(), extend(), insert(), pop(), remove(), reverse() and sort(), like Python standard list objects."
    – Random832
    Commented Mar 3, 2015 at 22:06
8

Pretty much any time you see "-like object" in Python documentation the author is being deliberately vague. The author has decided that enumerating all the required interfaces would be too much trouble, and is only saying that some of its interfaces are required. An object that implemented all the interfaces is guaranteed to work, but in most cases it will work with an object that implements much less.

With a "list-like object" probably the best you can do, short of inspecting the source code, is to infer whether it needs any of the mutable interfaces. If it only needs read-only access to the list, you can be pretty sure you don't need to implement any of the mutable sequence operations.

If it says "list-like object or iterator" you can provide something that implements the much simpler iterator interface.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.