gh-138178: Doc: Clarify that range is an immutable sequence

[Aniketsy]

(GH#138178)

This PR Clarifies that :class:range is an immutable :term:sequence type.

Please let me know if this fix needs any improvements . I’m open to feedback and happy to make changes based on suggestions.
Thankyou!

---

📚 Documentation preview 📚: https://cpython-previews--138184.org.readthedocs.build/

[ZeroIntensity]

It's not totally correct to say "the object returned by range", because range itself is the object. Instead, we should say something like "the range type is an iterator".

[Aniketsy]

Thank you for your feedback and corrections!

[AA-Turner]

Or along the lines of "an instance of range is an iterator"?

[ZeroIntensity]

That works too.

[TeamSpen210]

This isn’t correct - range isn’t an iterator, it’s a sequence (though it is iterable). Note how you can iterate the same range object multiple times, and next() fails. There’s a separate range_iterator type, like list_iterator etc.

[ZeroIntensity]

Oh, yeah. Let's just say "range supports iteration" or something like that.

[Aniketsy]

I have update with this
The :class:range type is iterable and supports iteration.

Please let me know , if this needs further improvement .

[ZeroIntensity]

There are a lot of iterators throughout the documentation, but this makes it seem like range is special. I think we should remove this note -- the iterator term already contains lots of information about iterators.

[StanFromIreland]

Suggested change

	The :class:`range` type is iterable and supports iteration.
	.. function:: repr(object)
	The :class:`range` type is iterable and supports iteration.
	.. function:: repr(object)

Please maintain the 2 line gap.

[brianschubert]

Saying all of "is [a] sequence", "is iterable" and "supports iteration" feels redundant. What about just linking the mention of "sequence" in the previous sentence to the sequence glossary entry, which begins

An iterable which supports efficient element access using integer indices ...

?

Or perhaps say "iterable sequence" if you think the extra emphasis is helpful

[pochmann3]

Why add that it "is iterable and supports iteration", especially right after saying that it's a sequence, which already implies that it's iterable?

The phrase "is iterable and supports iteration" even seems redundant in itself. What does "is iterable" mean if not "supports iteration"?

[Aniketsy]

Rather than being a function, :class:`range` is actually an immutable
   sequence type, as documented in :ref:`typesseq-range` and :ref:`typesseq`.

Should I update this and add sequence type to :term:sequence
Or It is already correct, and no changes are needed?

[skirpichev]

In this version pr looks correct (despite entirely misleading title and description).

Yet, I don't this this tiny change makes sense, as all existing three links already have reference to collections.abc.Sequence, which also mention glossary.

[Aniketsy]

@skirpichev Thank you for clarifying .
Should I close this PR?

[skirpichev]

Do whatever you wish, but please correct misleading title/description.

[mpkocher]

range is not an iterator, nor is list or set or frozenset etc...

range is an immutable sequence, while collections.abc.Iterator is (almost) always implemented as a stateful mutable entity.

When we call iter(thing) on a thing, it's essentially a factory to return a (stateful) Iterator instance.

In [1]: s = set("abc")

In [2]: next(s)
---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
Cell In[2], line 1
----> 1 next(s)

TypeError: 'set' object is not an iterator

In [3]: iter(s)
Out[3]: <set_iterator at 0x107a4ca40>

In [4]: it = iter(s)

In [5]: next(it)
Out[5]: 'c'

P.S. It can be handy to remember that Iterator is "NextAble" and implement __next__ (and also __iter__), whereas Iterable only implements __iter__.

https://docs.python.org/3/library/collections.abc.html#collections-abstract-base-classes

[serhiy-storchaka]

There is already a link to Sequence Types (typeseq). Is it necessary to add a link to the sequence term in glossary?

[picnixz]

I agree. ISTM there are too many links and this would confuse the reader. The sequence term doesn't mention range() but it mentions list, str, tuple and bytes. I would rather keep the current wording as I don't think it's necessary to overload the number of definitions.

The "Ranges" link says:

The range type represents an immutable sequence of numbers

In addition, changing it for range means that we need to change it for list() and tuple() as they do not have a link to the word "sequence".

[Aniketsy]

Thank you for your feedback!
That makes sense keeping the documentation consistent and avoiding too many links is important.
I agree that it’s best to keep the current wording and not add the glossary link to "sequence" for range().

Please let me know if any further changes are needed.

[picnixz]

I'm in favor of closing this, that is, leave the docs as is.