Attrs: Class nomenclature

[hynek]

It’s time for everyone’s favorite pastime: bikeshedding!

I’ve noticed that we’re a bit inconsistent with how we call __dict__ classes and __slots__ classes throughout the documentation.

I would like to unify it and add a glossary.

I’m pretty happy with “dict classes” but I’m not sure whether it should be “slot classes” or “slots classes”? The former sounds a bit better while the latter is technically more correct I guess?

Opinions especially from native Python and native English speakers? ;)

[Tinche]

Hrm the official docs seem very careful not to use any of the terms.

I vote for 'dict classes' and 'slot classes'.

[hynek]

I have another idea which I currently like most: how about “slotted classes”? Slot singular is technically incorrect, slots plural sounds weird. Slotted seems both correct and sounds well?

[ncoghlan]

While I'm not familiar with the details of how the attrs docs currently use these terms, for the language reference, we mainly use phrasing along the lines of "classes with[out] an instance dict", since that's the fundamental runtime distinction:

>>> class C(): pass
... 
>>> class S(): __slots__ = []
... 
>>> C().__dict__
{}
>>> S().__dict__
Traceback (most recent call last):                                                                                                                                                                      
  File "<stdin>", line 1, in <module>                                                                                                                                                                   
AttributeError: 'S' object has no attribute '__dict__'                                                                                                                                                  

Referring to classes without instance dictionaries as "slot" classes in general isn't quite right, since:

• you don't necessarily need to use the slots mechanism to define them, that's just the way you define them from pure Python code
• if you list __dict__ as one of your slots, you'll get regular dynamic instance attribute support back:

>>> class SD(): __slots__ = ["__dict__"]
...                                                                                                                                                                                                     
>>> SD().__dict__                                                                                                                                                                                       
{}                                                                                                                                                                                                      

So if you wanted strictly accurate terms, then "(instance) dict classes" and "descriptor-only classes" would be my suggestion.

However, I also think "dict class" and "slotted class" would be comprehensible, and the definition of the latter could clarify that it's a more colloquial alternative to "descriptor-only class".

[ambv]

While Nick's suggestions are the most correct technically, I'm afraid they're going to be confusing end-users. I like "dict classes" and "slotted classes". I think that's obvious to everybody except for the newest of newbies.

In general, I like to think in terms of "regular classes" vs. "fixed attribute classes" because this is what people use slots for. Yeah, I know, subclassing makes this murky but ¯\_(ツ)_/¯

So, I'm +0.5 to "dict classes" and "slotted classes" but I'd be +1 to "regular classes" and "slotted classes", esp. that slots=True is literally how this feature is configured in attrs.

[ncoghlan]

"regular classes" vs "slotted classes" would get a +1 from me, as the glossary entries themselves can then cover the translation of those terms into the technical definitions of "implicitly adds a per-instance dictionary" (regular class) and "doesn't add a per-instance dictionary" (slotted class).

[hynek]

The problem with terms like “regular” ist that classes can be “regular” in many ways. I personally like regular classes more too, but to the reader it immediately raises the question “regular how?” so it can’t be used isolated without context.

[ncoghlan]

@hynek Right, but the purpose of this issue is to let you write things like:

Setting `slots=True` creates a :term:`slotted class`, with dedicated storage
slots for each field (rather than the default behaviour of creating a
:term:`regular class` with an instance dictionary).

"regular class" would then be a hyperlink to the glossary entry that answer the "Regular how?" question.

[hynek]

True but I also want to have a language for eg the change log when something changes for either type without having to explain it over and over again. If it were just one place where I use it, I wouldn’t need a good term and could just explain it. :)