Add float linspace recipe to docs

[abarnert]

BPO	23226
Nosy	@rhettinger, @mdickinson
Files	stdtypes.rst.diff: Docs diff stdtypes.rst.diff: based on review

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/rhettinger'
closed_at = <Date 2016-09-06.23:36:31.514>
created_at = <Date 2015-01-12.22:40:48.383>
labels = ['type-feature', 'docs']
title = 'Add float linspace recipe to docs'
updated_at = <Date 2016-09-06.23:36:31.513>
user = 'https://bugs.python.org/abarnert'

bugs.python.org fields:

activity = <Date 2016-09-06.23:36:31.513>
actor = 'rhettinger'
assignee = 'rhettinger'
closed = True
closed_date = <Date 2016-09-06.23:36:31.514>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2015-01-12.22:40:48.383>
creator = 'abarnert'
dependencies = []
files = ['37684', '37685']
hgrepos = []
issue_num = 23226
keywords = ['patch']
message_count = 5.0
messages = ['233893', '233897', '234006', '234009', '274667']
nosy_count = 5.0
nosy_names = ['rhettinger', 'mark.dickinson', 'docs@python', 'python-dev', 'abarnert']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = None
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue23226'
versions = ['Python 3.5']

[abarnert]

In a recent thread on python-ideas (https://mail.python.org/pipermail/python-ideas/2015-January/030817.html), it was concluded that Python should not have a range-like type for floats in the stdlib, but there should be some simple discussion of the alternatives in the docs.

The attached diff describes the issues, demonstrates the simplest reasonable algorithm, and links to a recipe on ActiveState (which builds the same algorithm into a lazy sequence, and links to other recipes with different alternatives).

[abarnert]

As suggested by the review: removing unnecessary parenthetical, changing "ulp" to "digit", and fixing the recipe link.

[rhettinger]

This is too much. Try for a brief reference. This section of the docs is primarily about how range() works. Linspace() is at best a tangential discussion and shouldn't interfere with the usability of range() docs (a tool we actually have and that is in common use).

[abarnert]

So something like the first version below? Or should even the example be inline, as in the second version below? (Apologies if the formatting gets screwed up pasting from docs to bugs.)

---

Range objects are inappropriate for non-integral types, especially inexact types such as :class:`float`. In most cases, for such types, it is better to specify a count of numbers or intervals instead of a step size. For example:

   >>> start, stop, num = 0, 10, 11
   >>> step = (stop-start)/(num-1)
   >>> [start + i*step for i in range(num)]
   [0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0]

.. seealso::

• linspace recipe <http://code.activestate.com/recipes/579000/>_
  for an example lazy sequence built on this algorithm, and links
  to alternatives.

---

Range objects are inappropriate for non-integral types, especially inexact types such as :class:`float`. In most cases, it is better to specify a count of numbers or intervals instead of a step size, as in `[start + i*(stop-start)/(num-1) for i in range(num)]`.

.. seealso::

• linspace recipe <http://code.activestate.com/recipes/579000/>_
  for an example lazy sequence built on this algorithm, and links
  to alternatives.

[python-dev]

New changeset bb8fe61d78a4 by Raymond Hettinger in branch 'default':
Issue bpo-23226: Add linspace() recipe to the docs
https://hg.python.org/cpython/rev/bb8fe61d78a4