[New-bugs-announce] [issue16927] Separate built-in types from functions and group similar functions in functions.rst

[Ezio Melotti]

New submission from Ezio Melotti:

http://docs.python.org/3/library/functions.html currently lists all the builtin objects.
This include two main groups that should be separated in two different sections:  built-in types and functions.
In addition, similar/related functions should be grouped together.  This will make it easier to find similar functions, and will allow us to factor out some documentation that is repeated[0].

A possible division might be:

built-in types:
  dict, int, str, list, tuple, bytes, bool, object, float, complex, bytearray, set, frozenset, memoryview, range, slice

functions:
  base conversion: bin, oct, hex
  attribute-related: getattr, setattr, hasattr, delattr
  math-related: abs, pow, round, divmod, hash
  string-related: ascii, repr, format, chr, ord
  IO: input, print, open,
  OOP: staticmethod, classmethod, property, super
  introspection: isinstance, issubclass, callable, dir, help, vars, id, type, locals, globals
  sequence/iterable-related: len, min, max, sum, all, any, next, iter, sorted, reversed, enumerate,  filter, zip, map
  code-related: eval, exec, compile, __import__

This is just to give an idea -- the important thing is to rearrange the functions so that e.g. min/max, any/all, chr/ord, hex/oct/bin, getattr/setattr/hasattr/delattr, etc. are close to each other -- having separate sections is not strictly necessary though.  Some functions can also be listed on their own.

The table at the beginning of functions.rst and ctrl+f are enough to find functions, so I don't think that preserving the current alphabetical order is too useful -- grouping is more important.

[0] see e.g #16665. What is reported for hex() there is valid for bin() and oct() too, so a paragraph about how to use format() and its format codes can be added once at the top of the section.
This also came up on other issues where we were discussing about documenting the built-in types as "functions" (e.g. in str(someobj)), or as types (e.g. isinstance(someobj, type)).  A paragraph to explain this "duality" will help solve the problem.

----------
assignee: ezio.melotti
messages: 179632
nosy: chris.jerdonek, eric.araujo, ezio.melotti, terry.reedy
priority: normal
severity: normal
stage: needs patch
status: open
title: Separate built-in types from functions and group similar functions in functions.rst
type: enhancement
versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue16927>
_______________________________________