[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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Terry J. Reedy]

Terry J. Reedy added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Chris Jerdonek]

Chris Jerdonek added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Raymond Hettinger]

Changes by Raymond Hettinger :


--
assignee: rhettinger -> 

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Ezio Melotti]

Changes by Ezio Melotti :


--
stage: needs patch -> patch review
versions: +Python 3.6

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Nitika Agarwal]

Nitika Agarwal added the comment:

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

--
nosy: +nitika

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Nitika Agarwal]

Nitika Agarwal added the comment:

Hi,
Please review my patch attached.

--
keywords: +patch
Added file: http://bugs.python.org/file34506/issue16927_2.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

Éric Araujo added the comment:

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

--
versions: +Python 3.5 -Python 3.2, Python 3.3

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Nitika Agarwal]

Nitika Agarwal added the comment:

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

--
Added file: http://bugs.python.org/file34507/issue16927.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

Éric Araujo added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Nitika Agarwal]

Nitika Agarwal added the comment:

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

--
Added file: http://bugs.python.org/file34508/issue16927_3.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Nitika Agarwal]

Nitika Agarwal added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Terry J. Reedy]

Terry J. Reedy added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Raymond Hettinger]

Raymond Hettinger added the comment:

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.

--
nosy: +rhettinger

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Raymond Hettinger]

Changes by Raymond Hettinger :


--
versions:  -Python 2.7, Python 3.4

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Ezio Melotti]

Ezio Melotti added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Raymond Hettinger]

Raymond Hettinger added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Raymond Hettinger]

Changes by Raymond Hettinger :


--
assignee: ezio.melotti -> rhettinger

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Raymond Hettinger]

Raymond Hettinger added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Terry J. Reedy]

Terry J. Reedy added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Raymond Hettinger]

Raymond Hettinger added the comment:

Terry, I concur.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Martin Panter]

Changes by Martin Panter :


--
nosy: +vadmium

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com