This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author ezio.melotti
Recipients chris.jerdonek, eric.araujo, ezio.melotti, terry.reedy
Date 2013-01-11.05:49:54
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1357883404.71.0.215467038207.issue16927@psf.upfronthosting.co.za>
In-reply-to
Content
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.
History
Date User Action Args
2013-01-11 05:50:25ezio.melottisetrecipients: + ezio.melotti, terry.reedy, eric.araujo, chris.jerdonek
2013-01-11 05:50:04ezio.melottisetmessageid: <1357883404.71.0.215467038207.issue16927@psf.upfronthosting.co.za>
2013-01-11 05:50:03ezio.melottilinkissue16927 messages
2013-01-11 05:49:55ezio.melotticreate