The list of built-in functions is not alphabetical on https://docs.python.org/2/library/functions.html

[edsouza]

BPO	23512
Nosy	@birkenfeld, @terryjreedy, @ezio-melotti, @merwok
Files	issue23512.diff: Patch_1

^{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/ezio-melotti'
closed_at = <Date 2015-03-24.11:47:23.709>
created_at = <Date 2015-02-24.15:25:11.773>
labels = ['type-bug', 'docs']
title = 'The list of built-in functions is not alphabetical on https://docs.python.org/2/library/functions.html'
updated_at = <Date 2015-03-24.11:47:23.708>
user = 'https://bugs.python.org/edsouza'

bugs.python.org fields:

activity = <Date 2015-03-24.11:47:23.708>
actor = 'ezio.melotti'
assignee = 'ezio.melotti'
closed = True
closed_date = <Date 2015-03-24.11:47:23.709>
closer = 'ezio.melotti'
components = ['Documentation']
creation = <Date 2015-02-24.15:25:11.773>
creator = 'edsouza'
dependencies = []
files = ['38316']
hgrepos = []
issue_num = 23512
keywords = ['patch']
message_count = 13.0
messages = ['236505', '236837', '236845', '236846', '236852', '236868', '237021', '237023', '237081', '237086', '237087', '239114', '239115']
nosy_count = 8.0
nosy_names = ['georg.brandl', 'terry.reedy', 'ezio.melotti', 'eric.araujo', 'docs@python', 'python-dev', 'Paradisee', 'edsouza']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue23512'
versions = ['Python 2.7']

[edsouza]

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.

[Paradisee]

Well, these built-in are considered as non essential.

[terryjreedy]

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".

[edsouza]

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.

[Paradisee]

Maybe we could put them in another table below the current one.

[birkenfeld]

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 :)

[merwok]

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.

[ezio-melotti]

That was me in bpo-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 bpo-16927 for a proposed grouping that might help solve this issue.

[Paradisee]

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])

[edsouza]

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.

[terryjreedy]

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.

[python-dev]

New changeset 971d299d2cf3 by Ezio Melotti in branch '2.7':
bpo-23512: list non-essential built-in functions after the table. Patch by Carlo Beccarini.
https://hg.python.org/cpython/rev/971d299d2cf3

[ezio-melotti]

Fixed, thanks for the patch!