How recommended is using custom double underscore variables in Python?

Question

I was wondering, is it recommended/Pythonic to define and use custom double underscore variables/functions in a Python script? For example, __tablename__ as used in SQLAlchemy or __validateitem__() (a custom function that validates an item before applying __setitem__() to it).

If it does define that something magic happens, or that that specific variable/function is used indeed in a special way (like the two above examples), I feel it is a good idea using them.

I am interested in arguments on both best coding practices and potential risks in using this kind of naming.

Answer 1

From PEP8:

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

So, the advice is not to use the double underscore syntax for your own variables.