When to use one or two underscore in Python

Short answer: use a single leading underscore unless you have a really compelling reason to do otherwise (and even then think twice).

Long answer:

One underscore means "this is an implementation detail" (attribute, method, function, whatever), and is the Python equivalent of "protected" in Java. This is what you should use for names that are not part of your class / module / package public API. It's a naming convention only (well mostly - star imports will ignore them, but you're not doing star imports anywhere else than in your Python shell are you ?) so it won't prevent anyone to access this name, but then they're on their own if anything breaks (see this as a "warranty void if unsealed" kind of mention).

Two underscores triggers a name mangling mechanism. There are very few valid reason to use this - actually there's only one I can think of (and which is documented): protecting a name from being accidentally overridden in the context of a complex framework's internals. As an example there might be about half a dozen or less instances of this naming scheme in the whole django codebase (mostly in the django.utils.functional package).

As far as I'm concerned I must have use this feature perhaps thrice in 15+ years, and even then I'm still not sure I really needed it.

Look at documentation.

1. Single Underscore

From PEP-8:

_single_leading_underscore: weak "internal use" indicator. E.g. from M import * does not import objects whose name starts with an underscore.

2. Double Underscore:

From the Python tutorial:

Any identifier of the form __spam (at least two leading underscores, at most one trailing underscore) is textually replaced with _classname__spam, where classname is the current class name with leading underscore(s) stripped. This mangling is done without regard to the syntactic position of the identifier, so it can be used to define class-private instance and class variables, methods, variables stored in globals, and even variables stored in instances. private to this class on instances of other classes. Name mangling is intended to give classes an easy way to define “private” instance variables and methods, without having to worry about instance variables defined by derived classes, or mucking with instance variables by code outside the class. Note that the mangling rules are designed mostly to avoid accidents; it still is possible for a determined soul to access or modify a variable that is considered private.