[issue43896] Update the Sphinx directive for super from function to class

[Raymond Hettinger]

Raymond Hettinger  added the comment:

I've applied this PR but still am not sure that it makes readers better-off.

--
resolution:  -> fixed
status: open -> closed

___
Python tracker 

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

[issue43896] Update the Sphinx directive for super from function to class

[Géry]

Géry  added the comment:

> Elsewhere in the docs, all the links to this entry use the markup, 
> :func:`super` which looks nicer in the docs than the class reference.

I was suggesting only to update the block Sphinx directive “.. function::” to 
“.. class::” for defining the signature (so that the “class” prefix appears 
before the signature, like for the other built-in types), not the inline Sphinx 
roles “:func:” to “:class:” (since for instance `int` use both in the page: 
:class:`int` and :func:`int`).

Also the “class” prefix already appears in the interactive help when typing 
`help(super)`:

Help on class super in module builtins:

class super(object)
 |  super() -> same as super(__class__, )
 |  super(type) -> unbound super object
 |  super(type, obj) -> bound super object; requires isinstance(obj, type)
 |  super(type, type2) -> bound super object; requires issubclass(type2, type)
 |  Typical use to call a cooperative superclass method:
 |  class C(B):
 |  def meth(self, arg):
 |  super().meth(arg)
 |  This works for class methods too:
 |  class C(B):
 |  @classmethod
 |  def cmeth(cls, arg):
 |  super().cmeth(arg)

--

___
Python tracker 

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

[issue43896] Update the Sphinx directive for super from function to class

[Raymond Hettinger]

Raymond Hettinger  added the comment:

Also, the related text uses callable terminology, "it returns object that ...".

--

___
Python tracker 

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

[issue43896] Update the Sphinx directive for super from function to class

[Géry]

Géry  added the comment:

> Looking again, it seems to someone has already started applying class markup 
> despite previous decisions not to do so.

Yes, and he forgot super:

class bool([x])
class bytearray([source[, encoding[, errors]]])
class bytes([source[, encoding[, errors]]])
class complex([real[, imag]])
class dict(**kwarg)
class dict(mapping, **kwarg)
class dict(iterable, **kwarg)
class float([x])
class frozenset([iterable])
class int([x])
class int(x, base=10)
class list([iterable])
class memoryview(obj)
class object
class property(fget=None, fset=None, fdel=None, doc=None)
class range(stop)
class range(start, stop[, step])
class set([iterable])
class slice(stop)
class slice(start, stop[, step])
class str(object='')
class str(object=b'', encoding='utf-8', errors='strict’)
class tuple([iterable])
class type(object)
class type(name, bases, dict, **kwds)

--

___
Python tracker 

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

[issue43896] Update the Sphinx directive for super from function to class

[Raymond Hettinger]

Raymond Hettinger  added the comment:

-0 on doing this.  While class markup has crept into the Built-in Functions 
section, super() isn't really used this way (people don't subclass it or run 
isinstance on it).

Elsewhere in the docs, all the links to this entry use the markup, 
:func:`super` which looks nicer in the docs than the class reference.

In terms of markup, "function" is a role rather than an actual type, it is used 
for most callables whether or not ``isinstance(obj, type(lambda: None))`` 
returns true.

--

___
Python tracker 

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

[issue43896] Update the Sphinx directive for super from function to class

[Raymond Hettinger]

Raymond Hettinger  added the comment:

Looking again, it seems to someone has already started applying class markup 
despite previous decisions not to do so.

--
resolution: rejected -> 
status: closed -> open
versions:  -Python 3.6, Python 3.7, Python 3.8

___
Python tracker 

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

[issue43896] Update the Sphinx directive for super from function to class

[Raymond Hettinger]

Raymond Hettinger  added the comment:

In general, we've decided not to do this.  We use function mark-up in the 
section on builtin functions even though many of these are actually types.

We use class markup in other sections because that markup is well suited to 
listing all the associated methods and attributes.

--
nosy: +rhettinger
resolution:  -> rejected
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

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

[issue43896] Update the Sphinx directive for super from function to class

[Géry]

Change by Géry :


--
keywords: +patch
pull_requests: +24212
stage:  -> patch review
pull_request: https://github.com/python/cpython/pull/25489

___
Python tracker 

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

[issue43896] Update the Sphinx directive for super from function to class

[Géry]

New submission from Géry :

This PR updates the page [*Built-in 
Functions*](https://docs.python.org/3.9/library/functions.html#super) of the 
Python library documentation: `super` is not a `function` (`isinstance(super, 
type(lambda: None))` is `False`), it is a `type` (`isinstance(super, type)` is 
`True`), like `int`, `tuple`, `set`, etc. So it should get the same “class” 
prefix, i.e.

> **super**([*type*[, *object-or-type*]])

should become

> *class* **super**([*type*[, *object-or-type*]])

--
assignee: docs@python
components: Documentation
messages: 391458
nosy: docs@python, maggyero
priority: normal
severity: normal
status: open
title: Update the Sphinx directive for super from function to class
type: enhancement
versions: Python 3.10, Python 3.6, Python 3.7, Python 3.8, Python 3.9

___
Python tracker 

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