by Lyle Scott, III

Python and the Underscore Prefix

Underscore prefixes in Python provide a way to protect functions, methods, and variables...kinda. In Python, any notion of private variables simply does not exist. There are, though, some pythonic ways to declare that a variable, function, or method shouldn't be consumed outside of where it is being directly used.

Single Underscore

When you prefix something with a single underscore, it politely asks developers that interact with that code that the thing being prefixed should not be used in any direct manner other than calling it within the scope for which it was defined in. If you see it in third-party code, it means that you should not use or depend on it in any way.

Note, though, that the thing having a single underscore prefix can still be used as if it didn't have an underscore in the name, so having the prefix underscore is only symbolic and only represents some advice that hopefully people adhere to.

For example, 

class FooBar(object):
    foo = 'abc123'
    _bar = 'qwerty'

    def foofunc(self):
        print 'foofunc!'

    def _barfunc(self):
         print 'barfunc!'

The internal representation of the class looks like you think it would, listing the names of the defined variables and methods exactly as they were defined.

print dir(FooBar)
[ ..., '_bar', '_barfunc', ..., 'foo', 'foofunc' ..., ]

Abuse is easy, though. You can still use the single underscore prefixed things with their name like you would any other variable or method. Get why I mentioned it was based off the honor system?

foobar = FooBar()
foobar.foofunc()   # foofunc!
foobar._barfunc()  # barfunc!
print foobar._bar  # qwerty
foobar._bar = 'hello'
print foobar._bar  # hello

This example was with class methods and variables. The same rules apply to a variable or function definition in the module's scope.

Double Underscore

When you prefix something with a double underscore, it sternly implies to developers that interactict with that code that the thing being prefixed should absolutely and positively not be used in any direct manner other than calling it within the scope for which it was defined in.

The thing having a double underscore prefix becomes mangled, meaning that the class's variable or method gets renamed internally to protect the variable from being used directly. Like a single underscore prefix, this protection is only symbolic and is still based on the honor system, thought it is harder to use the variable or method.

Abuse is still possible, especially given that the result of manging always has the same pattern: _TheClassName is internally prefixed to the internal attribute.

For example,

class FooBar(object):
    foo = 'abc123'
    __bar = 'qwerty'

    def foofunc(self):
        print 'foofunc!'

    def __barfunc(self):
         print 'barfunc!'

The variable __bar and __barfunc are both mangled internally.

print dir(FooBar)

As you can see, __bar and __barfunc are mangled using the FooBar classname. This makes direct access more difficult and deliberate.

foobar = FooBar() 
foobar.__barfunc()         # AttributeError: 'FooBar' object has no attribute '__barfunc
foobar._FooBar__barfunc()  # barfunc!

Though access is possible, it is far from good practice!

Python Class vs Instance Variable

There are a million topics written on this, so I'm not going to delve into gory details. Instead, just checkout the snippet below. I think it says it all. 

class variable is a variable that is shared between all instances of a class. You access it by using the class's name in the dotted reference, rather than self (unless you are in a class method, where the self or cls argument could be used instead).  For example, if Car is a class with a variable number_tires and Honda, Jaguar, and VolksWagon were all instances, if number_tires was changed in any of the instances, then the new value would be reflected when I assessed it from Honda, Jaguar, or VolksWagon instances.

An instance variable is scoped to a single instance of a class. Meaning, if Car is a class with a variable number_tires and Honda, Jaguar, and VolksWagon were all instances, if number_tired was changed in the Honda instance, then the new value would ONLY be reflected in the Honda instance and the Jaguar and VolksWagon would be left to what ever value they were.

Accessing a class variable with the self (instance) reference copies that variable into the instance's scope.

class FooBar(object):
    foo = 0
    bar = 0

    def __init__(self): += 1 += 1 += 1

    def __str__(self):
        return '\n'.join((
            ' \t {} \t (class variable)'.format(,
            ' \t {} \t (instance variable)'.format(,
            ' \t {} \t (instance variable)'.format(,

As you can see,

  • the class variable was incremented accross all instances
  • the instance variable was only incremented for the single instance that it was being used in
  • (bonus) a class variable used as an instance variable gets copied to the instance's scope and does not effect the class version if you were to alter it
--------       1       (class variable)         1       (instance variable)         2       (instance variable)
--------       2       (class variable)         1       (instance variable)         3       (instance variable)
--------       3       (class variable)         1       (instance variable)         4       (instance variable)
US State Polygons with Events on a Google Map

For a weekend project I was messing with, I needed to have actionalable mouse events for each US state on a Google map. This is how I did it:

US State Polygons

I was looking for ways to draw state borders on a Google map and stumbled accross an XML file with a list of coordinates for each state that represents the coordinates that will outline each state. Using the Google Map API, you can create a Polygon from each set of points for each state. After you create the polygon, you can attach events to each state's polygon.

Data Conversion

Since Google Maps API is in JavaScript, I really wanted the JSON representation of the XML file... not to mention it would be nice to trim the data that isn't needed.


from pprint import pprint
from xml.dom import minidom

def xml2dict(path):
    data = []
    with open(path) as fp:
        xml = ''.join([line.strip() for line in fp.readlines()])
        doc = minidom.parseString(xml).documentElement
        for state in doc.childNodes:
            # str() to avoid the 'u' prefix for unicode strings.
            state_name = str(state.attributes['name'].value)
            points = []
            for point in state.childNodes:
            data.append([state_name, points])
    return data

def write_file(path, data):
    with open(path, 'w') as fp:
        fp.write('var stateCoords = ')
        pprint(data, stream=fp)

if __name__ == '__main__':
    xml_file = 'states.xml'
    out_file = 'coords.js'
    write_file(out_file, xml2dict(xml_file))