Separate built-in types from functions and group similar functions in functions.rst

[ezio-melotti]

BPO	16927
Nosy	@rhettinger, @terryjreedy, @ezio-melotti, @merwok, @cjerdonek, @vadmium
Files	issue16927_2.patch issue16927.patch issue16927_3.patch

^{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 = None
closed_at = None
created_at = <Date 2013-01-11.05:50:03.748>
labels = ['type-feature']
title = 'Separate built-in types from functions and group similar functions in functions.rst'
updated_at = <Date 2016-04-26.08:00:09.176>
user = 'https://github.com/ezio-melotti'

bugs.python.org fields:

activity = <Date 2016-04-26.08:00:09.176>
actor = 'rhettinger'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = []
creation = <Date 2013-01-11.05:50:03.748>
creator = 'ezio.melotti'
dependencies = []
files = ['34506', '34507', '34508']
hgrepos = []
issue_num = 16927
keywords = ['patch']
message_count = 17.0
messages = ['179632', '179762', '179765', '213710', '214056', '214057', '214065', '214066', '214067', '215611', '215623', '215630', '215634', '215636', '215641', '215643', '215644']
nosy_count = 7.0
nosy_names = ['rhettinger', 'terry.reedy', 'ezio.melotti', 'eric.araujo', 'chris.jerdonek', 'martin.panter', 'nitika']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue16927'
versions = ['Python 3.5', 'Python 3.6']

[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 bpo-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.

[terryjreedy]

I like this idea, including the function subdivisions. I once suggested moving the classes into the later builtins chapter, but it was pointed out to me that a) they once *were* functions (no longer relevant); b) they are callables (very relevant); and hence people who see "bytearray(b'abc')" might not know that bytearray *is* a class. A separate section could have a few lines of introduction explaining "Keyword 'class' and built-in name 'type' serve different roles in code. But when referring to a Python object, they are more or less synonyms. Classes are callable. The operators and methods of the instances returned by the following built-classes are explained in the Built-in Types section."

The index is another discovery method, one I use routinely, especially with the offline Windows help version of the docs, where one just types the first few letters of the name being sought in the index tab (much easier than the online click and search version). (Though the index entries might be improved a bit, that is another issue.)

code related: compile comes before eval and exec, both of which use compile on string input.

[cjerdonek]

I admit that I'm used to the alphabetical listing, but I like the idea for this organization. In fact, it's similar to how the Built-in Types page is organized: grouped by similarity rather than listed alphabetically.

Also just a note: strictly speaking there are built-in types not in the built-in types section (e.g. staticmethod and classmethod), but I think that's okay. (There can be a disclaimer to this effect in the intro sentences of the first grouping.)

Lastly, it might also be worth grouping the built-in types into subgroups (similar to how they're done for Built-in Types).

[nitika]

Hello everyone,
I am working on this issue to create a patch

[nitika]

Hi,
Please review my patch attached.

[merwok]

+Separate bulit-in types from functions and group similar functions
+------------------------------------------------------------------

This should not be in the patch. (I made the same remark on another issue, please take reviews into account.)

+Built-in Types :
+dict(), int(), str(), list(), tuple(), bytes(), set(),
+frozenset(), memoryview(), range()

These should use proper markup like :func:`dict` so that links get generated and specific style is applied. See docs.python.org/devguide/documenting.html for info about the markup we use.

+Functions :
+base conversion
+attribute-related
+math-related
+string-related
+IO
[etc.]

What Ezio meant was a reordering of the whole document. For example, a new heading (see the doc about markup) named “Math functions” and after it, the existing docs for abs, pow, round and divmod. Does that make the intent of this bug report clearer?

(Ezio also listed hash in the math functions, but it’s more related to dicts and sets than math itself. Making a patch also implies giving your opinion on the proposed changes; an idea written by a core developer is not always perfect :)

[nitika]

Hi,
I am attaching a new patch with some corrections which I got.Please help me where I am going wrong.

[merwok]

Thanks, the markup for built-in types is better. (You added hash to that list, but it’s a function returning an int, not a type.)

+Functions :
+base conversion: :func:`bin`, :func:`oct`, :func:`hex`
+attribute-related: :func:`getattr`, :func:`setattr`, :func:`hasattr`, :func:`delattr`
+math-related: :func:`abs`, :func:`pow`, :func:`round`, :func:`divmod`,
[etc]

This is a list of all functions, grouped by topic, which complements the list of all functions sorted mostly alphabetically. Ezio, is this what you had in mind, or was it regrouping the docs of functions in new sections with headings? (The latter sounds more useful to me.)

[nitika]

I have added hash in functions under the heading : "Math-Related"

[nitika]

@ezio Melotti
Please see if this is what you wanted.

[terryjreedy]

I think 'Builtin-in Types' should probably be 'Built-in Classes' as there is no longer any difference between types and classes. Note that after the unification, we added 'issubclass', not 'issubtype'.

type should at least be listed under types/classes. The one-parameter introspection use returns an existing instance of type rather than a new instance. In this, it is similar to bool, which returns an existing rather than new bool instance, and which is also used for introspection. I think both should be listed as classes, which they are, and then the intro to Introspection should mention that bool(ob) and type(ob) both return information about ob by returning existing instances of bool and type respectively.

I thought about whether we should merely add a categorized index or also re-arrange the entire page. It it the possibly of adding section paragraphs, including cross-references like the above, that pushes me in the latter direction. The math section intro could mention that functions of collections of numbers are in the Iterables section section.

[rhettinger]

FWIW, I don't think we should separate built-in types from built-in functions. Tools like str(x) and int(x) are frequently used as if there were functions. Tools like iter(x) and open(x) could be viewed as constructors. Tools like type(x) are both a function (the one-variable form) and a class constructor (the three variable form).

For the most part, I don't think the distinction is meaningful or helpful.

As a reference point, authors of Python books have avoided making a distinction and have favored the alphabetical ordering we have now (which has the virtue of making functions easy to find).

If you feel a need to provide groups of related functions, please do so in an addenda to the core function reference.

[ezio-melotti]

Tools like str(x) and int(x) are frequently used as if there were functions.

The description of each object already mentions the function/type duality, and links to https://docs.python.org/3/library/stdtypes.html.
If they are grouped together, a paragraph like "the objects in this section can be used both as constructors or as functions" can be added at the beginning of the section

Similarly a paragraph pointing to itertools can be used in the section that describes map/zip/filter/all/any/etc.

For the most part, I don't think the distinction is meaningful or helpful.

There are two distinctions I want to make:

1. grouping the built-in types;
2. grouping related functions;

1 should be especially useful to people that are new to the language. Here they can know quickly what are the Python equivalents of the objects they use in other languages (e.g. a structure similar to a C char*, or a JS object, or a PHP array...) and discover objects that might not exist in their language (e.g. sets, bytes, memoryviews).
2 is useful to find related functions. For example, if I'm looking at map(), I might be interested at zip() and filter() too, or if I'm looking at getattr(), having hasattr(), setattr() and delattr() nearby will make it easy to discover them and consult their docs.

As a reference point, authors of Python books have avoided making a
distinction and have favored the alphabetical ordering we have now
(which has the virtue of making functions easy to find).

The table at the beginning and ctrl+f makes the alphabetic order almost useless, so more meaningful orderings can be used instead.

[rhettinger]

This include two main groups that should be separated in
two different sections: built-in types and functions.

I forgot to mention that the docs have already been organized to cover the two groups. Section 3.2 has the built-in functions and Section 3.4 has the built-in types. Where they overlap (str and list, for example), section section addresses their use as a function (i.e. list(iterable) acts like a function that loops over an iterable to create a list, and str(x) like a function to lookup the string representation of an object).

The current organization has been somewhat successful and I don't want to damage it by regrouping.

This will make it easier to find similar functions,

This isn't the primary role of a library reference. That said, I would not object to either 1) an extra section that shows a high level grouping of functions or 2) adding to each function a list of see also links (the Microsoft Excel documentation takes that approach).

and will allow us to factor out some documentation that is repeated[0].

This should not be done either. For example, we really to want min() and max() to be completely documented in isolation from one another (this is a reference document, repeating definitions as dictionaries do is proper).

[rhettinger]

Nikita, your additional dispatch table looks like a reasonable addition. I'll wait on additional commentary before pushing it forward

1 should be especially useful to people that are new to the language
Ezio, please take care not to conflate the role of reference material (where people lookup what a function does) and tutorials (which introduce, synthesize, and organize).

Also take consider that the proposed groupings have some downsides as well (for example str and repr don't appear in the same grouping, likewise, int and round aren't in the same grouping).

And, I *really* don't want to separate-out types (that is what section 3.4 is for). You're fighting a long-standing decision to use 3.2 to talk about the tools as functions and again in 3.4 as types. For example, it is not helpful at all to classify range() as a type. Its usage is better grouped with looping idioms like range, zip, enumerate, sorted, and reversed.

A possible solution is to list words in more than one category so that int() would be listed as a type conversion (so it wouldn't get separated from str(), and listed math related (so it won't be separated from round() which is another way to convert a float to an integer).

This documentation page has proven useful in its current form to a great many users. We should take care not to muck-up one of the better pages in the docs. In particular, we REALLY don't want to factor-out redundant text -- as reference material, each function's description needs to stand-alone. This is not a page that people typically read start to finish in a book like form -- it is much closer to a dictionary or encyclopedia where topics are looked up directly.

[terryjreedy]

I would be happy enough to just add a second index section, with short annotations or commentaries about the categories -- nitika's patch with sentences added. I would put it after the current table, and not box the links. Short example:

The following functions convert an integer to a binary, octal, or hexadecimal string: :func:`bin`, :func:`oct`, :func:`hex`.

[rhettinger]

Terry, I concur.