Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Convert 10 PEPs to reSt #180

Merged
merged 2 commits into from
Jan 19, 2017
Merged

Convert 10 PEPs to reSt #180

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e2cf23d
Convert 10 PEPs to reSt
Mariatta Jan 14, 2017
a13cf77
Improvements, fix typos, add missing references url
Mariatta Jan 17, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
191 changes: 104 additions & 87 deletions pep-0212.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,163 +5,180 @@ Last-Modified: $Date$
Author: [email protected] (Peter Schneider-Kamp)
Status: Deferred
Type: Standards Track
Content-Type: text/x-rst
Created: 22-Aug-2000
Python-Version: 2.1
Post-History:


Introduction
============

This PEP describes the often proposed feature of exposing the loop
counter in for-loops. This PEP tracks the status and ownership of
this feature. It contains a description of the feature and
outlines changes necessary to support the feature. This PEP
summarizes discussions held in mailing list forums, and provides
URLs for further information, where appropriate. The CVS revision
history of this file contains the definitive historical record.
This PEP describes the often proposed feature of exposing the loop
counter in for-loops. This PEP tracks the status and ownership of
this feature. It contains a description of the feature and
outlines changes necessary to support the feature. This PEP
summarizes discussions held in mailing list forums, and provides
URLs for further information, where appropriate. The CVS revision
history of this file contains the definitive historical record.


Motivation
==========

Standard for-loops in Python iterate over the elements of a
sequence[1]. Often it is desirable to loop over the indices or
both the elements and the indices instead.
Standard for-loops in Python iterate over the elements of a
sequence [1]_. Often it is desirable to loop over the indices or
both the elements and the indices instead.

The common idioms used to accomplish this are unintuitive. This
PEP proposes two different ways of exposing the indices.
The common idioms used to accomplish this are unintuitive. This
PEP proposes two different ways of exposing the indices.


Loop counter iteration
======================

The current idiom for looping over the indices makes use of the
built-in 'range' function:
The current idiom for looping over the indices makes use of the
built-in 'range' function::

for i in range(len(sequence)):
# work with index i
for i in range(len(sequence)):
# work with index i

Looping over both elements and indices can be achieved either by the
old idiom or by using the new 'zip' built-in function[2]:
Looping over both elements and indices can be achieved either by the
old idiom or by using the new 'zip' built-in function [2]_::

for i in range(len(sequence)):
e = sequence[i]
# work with index i and element e
for i in range(len(sequence)):
e = sequence[i]
# work with index i and element e

or
or::

for i, e in zip(range(len(sequence)), sequence):
# work with index i and element e
for i, e in zip(range(len(sequence)), sequence):
# work with index i and element e


The Proposed Solutions
======================

There are three solutions that have been discussed. One adds a
non-reserved keyword, the other adds two built-in functions.
A third solution adds methods to sequence objects.
There are three solutions that have been discussed. One adds a
non-reserved keyword, the other adds two built-in functions.
A third solution adds methods to sequence objects.


Non-reserved keyword 'indexing'
===============================

This solution would extend the syntax of the for-loop by adding
an optional '<variable> indexing' clause which can also be used
instead of the '<variable> in' clause..
This solution would extend the syntax of the for-loop by adding
an optional '<variable> indexing' clause which can also be used
instead of the '<variable> in' clause.

Looping over the indices of a sequence would thus become:
Looping over the indices of a sequence would thus become::

for i indexing sequence:
# work with index i
for i indexing sequence:
# work with index i

Looping over both indices and elements would similarly be:
Looping over both indices and elements would similarly be::

for i indexing e in sequence:
# work with index i and element e
for i indexing e in sequence:
# work with index i and element e


Built-in functions 'indices' and 'irange'
=========================================

This solution adds two built-in functions 'indices' and 'irange'.
The semantics of these can be described as follows:
This solution adds two built-in functions 'indices' and 'irange'.
The semantics of these can be described as follows::

def indices(sequence):
return range(len(sequence))
def indices(sequence):
return range(len(sequence))

def irange(sequence):
return zip(range(len(sequence)), sequence)
def irange(sequence):
return zip(range(len(sequence)), sequence)

These functions could be implemented either eagerly or lazily and
should be easy to extend in order to accept more than one sequence
argument.
These functions could be implemented either eagerly or lazily and
should be easy to extend in order to accept more than one sequence
argument.

The use of these functions would simplify the idioms for looping
over the indices and over both elements and indices:
The use of these functions would simplify the idioms for looping
over the indices and over both elements and indices::

for i in indices(sequence):
# work with index i
for i in indices(sequence):
# work with index i

for i, e in irange(sequence):
# work with index i and element e
for i, e in irange(sequence):
# work with index i and element e


Methods for sequence objects
============================

This solution proposes the addition of 'indices', 'items'
and 'values' methods to sequences, which enable looping over
indices only, both indices and elements, and elements only
respectively.
This solution proposes the addition of 'indices', 'items'
and 'values' methods to sequences, which enable looping over
indices only, both indices and elements, and elements only
respectively.

This would immensely simplify the idioms for looping over indices
and for looping over both elements and indices:
This would immensely simplify the idioms for looping over indices
and for looping over both elements and indices::

for i in sequence.indices():
# work with index i
for i in sequence.indices():
# work with index i

for i, e in sequence.items():
# work with index i and element e
for i, e in sequence.items():
# work with index i and element e

Additionally it would allow to do looping over the elements
of sequences and dicitionaries in a consistent way:
Additionally it would allow to do looping over the elements
of sequences and dicitionaries in a consistent way::

for e in sequence_or_dict.values():
# do something with element e
for e in sequence_or_dict.values():
# do something with element e


Implementations
===============

For all three solutions some more or less rough patches exist
as patches at SourceForge:
For all three solutions some more or less rough patches exist
as patches at SourceForge:

'for i indexing a in l': exposing the for-loop counter[3]
add indices() and irange() to built-ins[4]
add items() method to listobject[5]
- 'for i indexing a in l': exposing the for-loop counter [3]_
- add ``indices()`` and ``irange()`` to built-ins [4]_
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest using ``...`` formatting consistently (or don't use it at all) CONSTANTs and function()s aren't the only things that can be wrapped by ``...``. If you change irange() to ``irange()``, I'd expect the following sentence to be formatted too:

This solution adds two built-in functions 'indices' and 'irange'.

I guess you have a script that converts these PEPs to reST format, but It would be nice to do some proofreading before sending a PR.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, @Mariatta has written a script to do the conversion.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While I think a moderate amount of proofreading and manual fix-up is warranted, I don't think the formatting needs to be perfect. We're mostly trying to improve the rendering of old historical documents, and if occasionally something isn't using a code font that is code, that's fine with me. Someone else can do some proofreading. The most important thing is that we don't accidentally break the meaning of a PEP.

- add ``items()`` method to listobject [5]_

All of them have been pronounced on and rejected by the BDFL.
All of them have been pronounced on and rejected by the BDFL.

Note that the 'indexing' keyword is only a NAME in the
grammar and so does not hinder the general use of 'indexing'.
Note that the 'indexing' keyword is only a ``NAME`` in the
grammar and so does not hinder the general use of 'indexing'.


Backward Compatibility Issues
=============================

As no keywords are added and the semantics of existing code
remains unchanged, all three solutions can be implemented
without breaking existing code.
As no keywords are added and the semantics of existing code
remains unchanged, all three solutions can be implemented
without breaking existing code.


Copyright
=========

This document has been placed in the public domain.
This document has been placed in the public domain.


References
==========

[1] http://docs.python.org/reference/compound_stmts.html#for
[2] Lockstep Iteration, PEP 201
[3] http://sourceforge.net/patch/download.php?id=101138
[4] http://sourceforge.net/patch/download.php?id=101129
[5] http://sourceforge.net/patch/download.php?id=101178
.. [1] http://docs.python.org/reference/compound_stmts.html#for

.. [2] Lockstep Iteration, PEP 201


Local Variables:
mode: indented-text
indent-tabs-mode: nil
End:
.. [3] http://sourceforge.net/patch/download.php?id=101138

.. [4] http://sourceforge.net/patch/download.php?id=101129

.. [5] http://sourceforge.net/patch/download.php?id=101178



..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
End:
Loading