CODEWITHSUNDEEP
python
Dave Anderson
Dave Anderson

Reputation: 118

Python double leading and trailing underscore usage for class attributes

In regards to naming conventions for class attributes, PEP 8 states:

__double_leading_and_trailing_underscore__: "magic" objects or attributes that live in user-controlled namespaces. E.g. __init__, __import__ or __file__. Never invent such names; only use them as documented.

Does this imply to never use this convention or only use in a "user-controlled namespace."

I have seen this used in other libraries not directly included within Python a few times. From what I gather, using this convention is more specific to implementing an API.

A couple of examples would be providing an __acl__ to a class in Pyramid, or adding __tablename__ to a class in SQLAlchemy.

Is using this convention in the context of an API OK, or should it only ever be used / reserved for Python?

Upvotes: 1

Views: 654

Answers (1)

Steve Jessop
Steve Jessop

Reputation: 279315

Pyramid and SQLAlchemy have disobeyed the instruction not to invent such names.

It's not clear to me what you mean by "using this convention in the context of an API", but once they've invented the name, you don't have much choice but to use it as documented by them.

There's no difference between you inventing such names, and inventing them only in user-controlled namespaces. Since you're a user of Python, any namespace that you could put the name into is user-controlled. If you're modifying the Python source to add a new extension to the language that requires some "magic" name, then you can invent one. I expect if you're doing this, you'll usually be in communication with GvR one way or another, so you can ask his opinion directly :-)

What's happening here is that the library authors want a name that none of their users will use by accident to mean something else. The Python language also wants names that no user will use by accident to mean something else, so it "reserves" names of a particular format for use by the language. But then the library-writer has decided to "steal" one of those reserved names and use it anyway, because they feel that's the best way to avoid a clash with one of their users. They have tens of thousands of users, most of whom they don't know anything about. But there's only one Python language spec, and they have access to it. So if a clash occurs the library developers will know about it, which is the plus side, but it will be their fault and difficult to fix, which is the minus side.

Perhaps they're hoping that by using it, the have de facto reserved it for themselves, and that GvR will choose never to use a name that a popular library has already used. Or perhaps they've discussed it on the relevant mailing lists and obtained an exception to the usual rule -- I don't know whether there's a process for that.

Upvotes: 2

Related Questions