Counter object in Python with public and private methods

Question

I am trying to implement an open source desktop application with python. I want to provide both a gui and an API. I know there is no private methods in python but i am trying to find the most elegant way to keep some methods private. I do not want my users to see all list of methods while using API. After some research, I come up with the implementation below and wondering if there is any problem with my implementation of this concept and if there is any room for improvement. Please provide me a review and do not hesitate to ask any questions you have. Here is my try:

from pprint import pprint


# CamelCase because it "acts" like a class
def CounterController():
    class CounterControllerPrivate(object):
        def __init__(self):
            self.counter = 0

        def add_one(self):
            self.counter += 1

        def reset(self):
            self.counter = 0

        def get_counter(self):
            return self.counter

    counter_controller = CounterControllerPrivate()

    class CounterControllerPublic(object):
        def add_one_endpoint(self):
            counter_controller.add_one()
            return counter_controller.get_counter()

        def reset_endpoint(self):
            counter_controller.reset()
            return counter_controller.get_counter()

    return CounterControllerPublic()


# counter attribute is not accessible from out here
controller = CounterController()

print(controller.add_one_endpoint())
print(controller.add_one_endpoint())
print(controller.reset_endpoint())

pprint(dir(controller))

Answer 1

The private objects and attributes are easily accessed using inspect.getclosurevars:

>>> c = CounterController()
>>> import inspect
>>> inspect.getclosurevars(c.add_one_endpoint)
ClosureVars(nonlocals={'counter_controller': <__main__.CounterController.<locals>.CounterControllerPrivate object at 0x10a047cf8>}, globals={}, builtins={}, unbound={'add_one'})
>>> _.nonlocals['counter_controller']
<__main__.CounterController.<locals>.CounterControllerPrivate object at 0x10a047cf8>
>>> _.counter
0

So you might consider whether it's worth spending a lot of effort on this approach. Personally I would spend the effort on API documentation instead.

Answer 2

Python classes operate under the principle of "We are all consenting adults here".

This means that there is no real way to encapsulate your methods completely, there will always be a way to access them regardless (except if you make your code a thin wrapper on a C++ class with private members, or similar, and even that might not be foolproof).

The convention is for method names with one leading underscore to be considered internal methods, probably not for public consumption and method names with two leading underscores to be the closest thing to private you will get without a great effort. Python does some name mangling on the latter (by inserting the class name).

What this means is that these methods will still show up when calling dir(obj), however, when working in an interactive session with tab completion, you need to explicitly start typing obj._ObjectClass__m[Tab] to access them, you will not get them with a simple obj.m[Tab]. It also means that when a subclass defines a method/attribute with the same name, there is no naming conflict with the base class.

In your documentation of the API you do not need to describe these methods at all, since it is the standard that they are not to be used. They should probably still have docstrings in the source code, though, if only for your own sake.

Some good further reading can be found here: https://stackoverflow.com/questions/3385317/private-variables-and-methods-in-python.

These conventions are also encoded in Python's official style-guide, PEP8:

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

• single_trailing_underscore_: used by convention to avoid conflicts with Python keyword, e.g. Tkinter.Toplevel(master, class_='ClassName')

• __double_leading_underscore: when naming a class attribute, invokes name mangling (inside class FooBar, __boo becomes _FooBar__boo; see below).

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