[New-bugs-announce] [issue16927] Separate built-in types from functions and group similar functions in functions.rst
report at bugs.python.org
Fri Jan 11 06:50:04 CET 2013
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.
A possible division might be:
dict, int, str, list, tuple, bytes, bool, object, float, complex, bytearray, set, frozenset, memoryview, range, slice
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.
 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.
nosy: chris.jerdonek, eric.araujo, ezio.melotti, terry.reedy
stage: needs patch
title: Separate built-in types from functions and group similar functions in functions.rst
versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4
Python tracker <report at bugs.python.org>
More information about the New-bugs-announce