7

The Python docs lists property() as a built-in function.

However, the function description has the keyword "class" in front of it in the docs.

class property(fget=None, fset=None, fdel=None, doc=None)

This also happens with

class set([iterable])

and

class slice(stop)

What does this mean? - why are classes listed under built-in functions. Is this just a documentation issue or is there a technical reason?

EDIT: I am not asking about how property() works.

Kevin L.
  • 1,371
  • 11
  • 24
  • 1
    i don't understand why this is a duplicate. i wasn't asking about how the @property decorator works, i'm asking about why it is a class listed as a function. – Kevin L. Jan 25 '18 at 09:54
  • I dont understand why this was marked as duplicate - i was researching it because I thought it was just because it returned a class, - also other things in the docs are marked as classmethods (which I kind of understand). But why would htese be marked as returning things, where other things that return arn't marked. This is an *excellent* question which is *not* a duplicate of the one listed in the comment before: PErhaps you should reword it as 'Some functions are listed as a class in front, such as these, what does that mean?' – Jmons Jan 25 '18 at 09:57
  • precisely, thank you – Kevin L. Jan 25 '18 at 09:58
  • 1
    You are correct if you want to be pedantic, but since a class can be called as if it was a function, then the distinction is burred. `property` is not the only example, `str`, `int`, `float`, `set`, `list`, `type` and more are all listed as functions but are all classes. This is really a documentation issue, nothing more. – cdarke Jan 25 '18 at 10:01
  • A class is basically something that when called returns an instance of its type. `property`, `set` and `slice` all fit that description; e.g. `property()` → ``, `isinstance(property(), property)` → `True`. See the duplicate for a pure Python implementation of `property` as a class and read why it is implemented that way. – deceze Jan 25 '18 at 10:02
  • 1
    well it was a genuine question. i wasn't trying to be pedantic. there might be a technical reason why classes are listed under functions: are classes technically functions? who am I (or you for that matter) to say? – Kevin L. Jan 25 '18 at 10:04
  • 1
    @KevinLee: don't get me wrong, I think it is a reasonable question and not a duplicate. Classes are not functions, but in normal use they might as well be. I guess the authors could not think of a better name for the grouping. – cdarke Jan 25 '18 at 10:05
  • 2
    the doc says "...has a number of functions and *types* built into it...", `property` is one of those type constructors, [see cpython ref](https://github.com/python/cpython/blob/v3.6.3/Python/bltinmodule.c#L2728-L2753), btw I changed my mind and voted to reopen. – georgexsh Jan 25 '18 at 10:06
  • As an aside to this question, since these are classes then their names should follow PEP008, i.e. `Property`, `Str`, `Int`, etc. I can hear the howls of derision from here. In terms of usability, to apply the PEP008 naming standard to these common classes would be a step too far for most (not to mention the code you would break). Maybe for Python 4. – cdarke Jan 25 '18 at 10:15
  • Sorry to push for clarification, from the above , Is the documentation saying that this is a class which is being called, or that its returning a class? - the similar documentation syntax (for example here: https://docs.python.org/3/library/inspect.html#inspect.Signature.from_callable ) would suggest that its indicating the "type" of thing you are calling, and has nothing to do with the return type. (in as such this makes it a bit at odds with other languages which document return type in front of the function call). – Jmons Jan 25 '18 at 10:22
  • 1
    The only problem I can see is that the table heading in which `property` is listed says *"Built-in Functions"*, but the sentence above it correctly says *"functions and types"*. `property` is prefixed with *`class`* because it is a class (type). – deceze Jan 25 '18 at 10:24
  • are you 100% sure it is just a documentation issue? if it is just a documentation issue, then my question is certainly not a duplicate as you have marked it to be. – Kevin L. Jan 25 '18 at 10:28
  • 1
    Well, again, `property` *is* a class and so is correctly prefixed with *`class`*, and the explanatory sentence in the documentation lumps *"functions and types"* (which is an alternative way to say *class*) together. So the only issue seems to be that the chosen table heading is sub-optimal. Does this warrant a post on SO? Can you make a stronger case for your question? – deceze Jan 25 '18 at 10:36
  • 1
    The documentation is _really_ unclear unless you already know what it means, especially since it (and the language) treat classes as callable. I don't see any harm in having a question and answer explaining that since it's clearly not obvious to everyone. – Useless Jan 25 '18 at 10:43
  • 5
    whether or not my question warrants a post on SO is a completely different issue from whether it is a duplicate. marking my question as a duplicate prevents me from getting the proper answer to my question, regardless of how trivial the question is. If the answer is indeed that the title of the documentation is sub-optimal (and not some other technical reason), then why can't the question be answered? – Kevin L. Jan 25 '18 at 10:48
  • Well… *"Why is there a "class" keyword in front of [`property`]"* → Because it is a class. → See how it works. → Duplicate. But fine, it's been reopened anyway. – deceze Jan 25 '18 at 10:54
  • 1
    @deceze - thanks, if you are certain of the answer, then please answer the question. it helps people like me who are learning and are confused by the documentation. – Kevin L. Jan 25 '18 at 11:05
  • 2
    I'd rather one of the other enthusiasts here post an answer; the only thing I can say is *because it is a class*, which is too trivial. – deceze Jan 25 '18 at 11:08

1 Answers1

3

The Python glossary defines a function as:

A series of statements which returns some value to a caller. It can also be passed zero or more arguments which may be used in the execution of the body.

A class can be passed arguments, and returns a value to the caller, so arguably by this definition classes are functions*.

In addition (as deceze points out in the comments), a class should always return an instance of itself – set, property, slice, etc. all return instances of set, property, slice, etc. respectively – so set, property and friends are all also classes, and so they are documented as such:

class set([iterable])

meaning that set is a class, not that it returns one.

I would guess that set etc. are documented in the "built-in functions" page because a) they are callable, and b) it's convenient to have all the documentation for "things you can call" in one place.

*Strictly speaking, isinstance(C, types.FunctionType) is false for any class C (as far as I can tell), but classes are certainly callables (isinstance(C, typing.Callable) is true), which is maybe a more useful property to think about.

ash
  • 5,139
  • 2
  • 27
  • 39
  • I think one more reason might be that we should understand that these are not just functions (or more accurately, work as function), they are also classes having associated attributes with them. – TrigonaMinima Jan 25 '18 at 12:16
  • So what you are saying is that the documentation should be titled “Built in Callables” since functions, classes and decorators are all callables. – Kevin L. Jan 25 '18 at 13:59