classification
Title: Missing cross-reference in sequence glossary entry
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: akuchling, amaury.forgeotdarc, docs@python, maker, methane, ncoghlan, python-dev, r.david.murray
Priority: normal Keywords:

Created on 2012-12-19 12:14 by methane, last changed 2014-10-10 23:51 by r.david.murray. This issue is now closed.

Files
File name Uploaded Description Edit
issue16728.txt akuchling, 2014-02-15 22:04
Messages (13)
msg177737 - (view) Author: Inada Naoki (methane) * (Python committer) Date: 2012-12-19 12:14
http://docs.python.org/3.3/glossary.html#term-sequence

__getitem__ and __len__ are required for sequence type.
(__iter__ is not required because types having __getitem__ are already iterator.)

.__contains__(), .index() and .count() is not required for sequence.

For example, following class should be sequence.

class Foo:
    def __getitem__(self, index):
        if not isinstance(index, int):
            raise TypeError
        if index >= 3:
            raise IndexError
        return index

    def __len__(self):
        return 3
msg177738 - (view) Author: Inada Naoki (methane) * (Python committer) Date: 2012-12-19 12:31
In Python 3.3:

In [33]: issubclass(Foo, collections.abc.Sequence)
Out[33]: False
msg177753 - (view) Author: Amaury Forgeot d'Arc (amaury.forgeotdarc) * (Python committer) Date: 2012-12-19 16:10
Careful, though: dict also provides these methods, but I would not consider it a Sequence.
msg177760 - (view) Author: Inada Naoki (methane) * (Python committer) Date: 2012-12-19 16:41
I think PySequence_Check() has same problem.

OTOH, mapping definition says:

> A container object that supports arbitrary key lookups and implements the methods specified in the Mapping or MutableMapping abstract base classes.
- http://docs.python.org/3.3/glossary.html#term-mapping

So the mapping should implement all methods defined in collections.abc.Mapping.

If the sequence should implement all methods defined in collections.abc.Sequence, it's a documentation bug.

Is there a common view about what is the sequence?
msg177868 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-12-21 08:27
Many algorithms that require a sequence only need __len__ and __getitem__. The term "sequence" is used to distinguish such containers from mere iterables that only provide "__iter__" (and may be consumed by iteration). The glossary entry covers this use of the term.

collections.abc.Sequence is a much richer interface, which defines many additional operations beyond those iteration, indexing and slicing. Types which implement that full API can be registered explicitly (or else an application can define it's own custom ABC for a subset of the Sequence API).

However, the glossary entry should link to http://docs.python.org/3.3/library/stdtypes#sequence-types-list-tuple-range to expand on the second meaning of the term.

PySequence_Check is an unreliable guide (albeit not quite as unreliable as PyMapping_Check) that checks a CPython implementation detail.
msg177869 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-12-21 08:28
As Amaury notes, implicit ducktyping is not feasible for sequences or mappings, as the method names overlap - you have to add explicit semantic information to say which kind of container you're implementing.
msg177870 - (view) Author: Inada Naoki (methane) * (Python committer) Date: 2012-12-21 09:24
Thanks, Nick.

I see that the "sequence" doesn't have strict definition.

Though, I think collections.abc module's document should describe
this manner. For example:

"But checking type with these abc may be too strict for most case.
For example, some user defined sequence class may not cover
:class:`Sequence` abc. Using :term:`EAFP` manner is preferred in Python."
msg177873 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-12-21 10:22
No, that runs counter to the purpose of ABCs. If you have a type that is "good enough" for your purposes, then you can just register it.
msg177877 - (view) Author: Inada Naoki (methane) * (Python committer) Date: 2012-12-21 13:55
So, I feel the 2nd meaning of "sequence" should be collections.abc.(Mutable)Sequence.

"sequence types in stdlib" have richer API then the ABC. (e.g. comparison, +, *, etc...)
They are "APIs that sequence may have" but not "APIs makes the type sequence."
msg177878 - (view) Author: Inada Naoki (methane) * (Python committer) Date: 2012-12-21 13:57
And nice symmetry with mapping entry.
msg211299 - (view) Author: A.M. Kuchling (akuchling) * (Python committer) Date: 2014-02-15 22:04
Here's a possible patch that mentions collections.abc.Sequence.  I left out MutableSequence, because I couldn't see how to mention it without making the definition longer and more complicated.  

(It could be objected that this is the *glossary*, and is supposed to provide brief descriptions of terms, not precisely detailed descriptions.  In that case, the patch could simply be rejected.)
msg211301 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-02-15 22:11
New changeset 30d0816939a3 by Andrew Kuchling in branch '3.3':
#16728: Mention collections.abc.Sequence in 'sequence' glossary entry
http://hg.python.org/cpython/rev/30d0816939a3
msg229051 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-10-10 23:51
Looks like this was left open for post-commit review, but since no one has objected (and it looks fine to me) I'm going to close it.
History
Date User Action Args
2014-10-10 23:51:14r.david.murraysetstatus: open -> closed

nosy: + r.david.murray
messages: + msg229051

resolution: fixed
stage: commit review -> resolved
2014-02-16 14:52:51akuchlingsetstage: needs patch -> commit review
2014-02-15 22:11:17python-devsetnosy: + python-dev
messages: + msg211301
2014-02-15 22:04:59akuchlingsetfiles: + issue16728.txt
nosy: + akuchling
messages: + msg211299

2012-12-21 13:57:56methanesetmessages: + msg177878
2012-12-21 13:55:42methanesetmessages: + msg177877
2012-12-21 10:22:46ncoghlansetmessages: + msg177873
2012-12-21 09:24:03methanesetmessages: + msg177870
2012-12-21 08:29:00ncoghlansetmessages: + msg177869
2012-12-21 08:27:27ncoghlansetassignee: docs@python
type: enhancement
components: + Documentation, - Library (Lib)
title: collections.abc.Sequence shoud provide __subclasshook__ -> Missing cross-reference in sequence glossary entry
nosy: + docs@python, ncoghlan

messages: + msg177868
stage: needs patch
2012-12-19 16:41:53methanesetmessages: + msg177760
2012-12-19 16:32:56makersetnosy: + maker
2012-12-19 16:10:53amaury.forgeotdarcsetnosy: + amaury.forgeotdarc
messages: + msg177753
2012-12-19 12:31:05methanesetmessages: + msg177738
2012-12-19 12:14:49methanecreate