classification
Title: The list of built-in functions is not alphabetical on https://docs.python.org/2/library/functions.html
Type: behavior Stage: resolved
Components: Documentation Versions: Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: Paradisee, docs@python, edsouza, eric.araujo, ezio.melotti, georg.brandl, python-dev, terry.reedy
Priority: normal Keywords: patch

Created on 2015-02-24 15:25 by edsouza, last changed 2015-03-24 11:47 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
issue23512.diff Paradisee, 2015-03-03 13:56 Patch_1 review
Messages (13)
msg236505 - (view) Author: Edward D'Souza (edsouza) Date: 2015-02-24 15:25
The list of built-in functions at the top of https://docs.python.org/2/library/functions.html is not alphabetical. Specifically, (apply, coerce, intern, buffer) allow appear out of order at the end of the list, instead of where they should be alphabetically.
msg236837 - (view) Author: Carlo Beccarini (Paradisee) * Date: 2015-02-27 20:50
Well, these built-in are considered as non essential.
msg236845 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2015-02-27 21:37
The table was deliberately created as it is and I think it should be left as is.  Those four functions appear 'out of order' in a separate section "3. Non-essential Built-in Functions".
msg236846 - (view) Author: Edward D'Souza (edsouza) Date: 2015-02-27 21:43
Doesn't make sense to me. The page says "They are listed here in alphabetical order.", which isn't true.

Furthermore, not putting them in order screws up people who assume it is in alphabetical order and try to search for a function with their eyes. 

If they are so special, put them in a separate table. This inconsistency is simply disrespectful to the reader, IMO.
msg236852 - (view) Author: Carlo Beccarini (Paradisee) * Date: 2015-02-27 22:42
Maybe we could put them in another table below the current one.
msg236868 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2015-02-28 06:59
I agree with Edward. The table makes no distinction between the two group of builtins, so it is confusing why it would list them not in alphabetical order.

I wouldn't go so far as to call it "disrespectful" though :)
msg237021 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2015-03-02 06:37
IIRC the table was added in a 3.x branch and backported to 2.7; the developer doing the backport added the functions missing in 3.x to the end of the table, thinking that re-ordering was not worth the trouble.
msg237023 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2015-03-02 06:52
That was me in #10299 (the issue contains a discussion about the ordering in the last few messages).

Since there are only 4 functions, I think it would be ok removing them from the table and instead add a sentence like "In addition, there are other 4 built-in functions that are no longer considered essential: apply, buffer, coerce, and intern.  They are documented in the Non-essential Built-in Functions section.".

See also #16927 for a proposed grouping that might help solve this issue.
msg237081 - (view) Author: Carlo Beccarini (Paradisee) * Date: 2015-03-02 20:18
diff -r 3019effc44f2 Doc/library/functions.rst
--- a/Doc/library/functions.rst	Mon Mar 02 11:17:05 2015 -0500
+++ b/Doc/library/functions.rst	Mon Mar 02 21:13:27 2015 +0100
@@ -22,10 +22,10 @@
 :func:`classmethod`  :func:`getattr`    :func:`map`         |func-repr|_       :func:`xrange`
 :func:`cmp`          :func:`globals`    :func:`max`         :func:`reversed`   :func:`zip`
 :func:`compile`      :func:`hasattr`    |func-memoryview|_  :func:`round`      :func:`__import__`
-:func:`complex`      :func:`hash`       :func:`min`         |func-set|_        :func:`apply`
-:func:`delattr`      :func:`help`       :func:`next`        :func:`setattr`    :func:`buffer`
-|func-dict|_         :func:`hex`        :func:`object`      :func:`slice`      :func:`coerce`
-:func:`dir`          :func:`id`         :func:`oct`         :func:`sorted`     :func:`intern`
+:func:`complex`      :func:`hash`       :func:`min`         |func-set|_        ..
+:func:`delattr`      :func:`help`       :func:`next`        :func:`setattr`    ..
+|func-dict|_         :func:`hex`        :func:`object`      :func:`slice`      ..
+:func:`dir`          :func:`id`         :func:`oct`         :func:`sorted`     ..
 ===================  =================  ==================  =================  ====================
 
 .. using :func:`dict` would create a link to another page, so local targets are
@@ -1699,6 +1699,11 @@
 Python programmers, trainers, students and book writers should feel free to
 bypass these functions without concerns about missing something important.
 
+===================  =================  ==================  =================
+..                     Non-essential    Built-in Functions  ..
+===================  =================  ==================  =================
+:func:`apply`        :func:`buffer`     :func:`coerce`      :func:`intern`
+===================  =================  ==================  =================
 
 .. function:: apply(function, args[, keywords])
msg237086 - (view) Author: Edward D'Souza (edsouza) Date: 2015-03-02 21:14
I think putting them in a separate table is good, but I think it makes more sense to appear right below the existing table at the top of the page. For better or worse, these "non-essential" functions are still builtins in Python 2.

It would be disconcerting if you went to this page looking for a builtin (eg. coerce) and couldn't find it at the top of the page with the other builtins.

Above all, the list of "builtins" should be accurate as to what builtins actually exist in Python 2.
msg237087 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2015-03-02 21:59
> It would be disconcerting if you went to this page looking for a builtin [and had trouble finding it]

I agree with this premise.  Since Idle, and I presume other IDEs, color code apply, coerce, intern, and buffer as builtins indistinguishably from all the others, these 4 should somehow be easy to find in or just below the rest.  I have no particular opinion on the best way to do so.
msg239114 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-03-24 11:45
New changeset 971d299d2cf3 by Ezio Melotti in branch '2.7':
#23512: list non-essential built-in functions after the table.  Patch by Carlo Beccarini.
https://hg.python.org/cpython/rev/971d299d2cf3
msg239115 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2015-03-24 11:47
Fixed, thanks for the patch!
History
Date User Action Args
2015-03-24 11:47:23ezio.melottisetstatus: open -> closed
resolution: fixed
messages: + msg239115

stage: needs patch -> resolved
2015-03-24 11:45:31python-devsetnosy: + python-dev
messages: + msg239114
2015-03-04 19:07:18Paradiseesetfiles: - functions.rst
2015-03-03 13:56:04Paradiseesetfiles: + issue23512.diff
keywords: + patch
2015-03-03 13:39:17ezio.melottisetassignee: docs@python -> ezio.melotti
2015-03-03 02:47:27Paradiseesetfiles: - functions.rst
2015-03-02 22:00:46Paradiseesetfiles: + functions.rst
2015-03-02 21:59:58terry.reedysetmessages: + msg237087
2015-03-02 21:14:26edsouzasetmessages: + msg237086
2015-03-02 20:27:08Paradiseesetfiles: + functions.rst
2015-03-02 20:23:09SilentGhostsetfiles: - functools.rst
2015-03-02 20:18:17Paradiseesetfiles: + functools.rst

messages: + msg237081
2015-03-02 06:52:56ezio.melottisetnosy: + ezio.melotti
messages: + msg237023
2015-03-02 06:37:56eric.araujosetnosy: + eric.araujo
messages: + msg237021
2015-02-28 06:59:45georg.brandlsetnosy: + georg.brandl
messages: + msg236868
2015-02-27 23:25:51r.david.murraysettitle: The list of built-in http://text-processing.com/demo/sentiments is not alphabetical on https://docs.python.org/2/library/functions.html -> The list of built-in functions is not alphabetical on https://docs.python.org/2/library/functions.html
2015-02-27 22:42:56Paradiseesetmessages: + msg236852
2015-02-27 21:43:18edsouzasetmessages: + msg236846
2015-02-27 21:37:39terry.reedysetnosy: + terry.reedy

messages: + msg236845
stage: needs patch
2015-02-27 20:50:39Paradiseesetnosy: + Paradisee

messages: + msg236837
title: List of builtins is not alphabetical on https://docs.python.org/2/library/functions.html -> The list of built-in http://text-processing.com/demo/sentiments is not alphabetical on https://docs.python.org/2/library/functions.html
2015-02-24 15:25:11edsouzacreate