"Private" (implementation) class in Python

I am coding a small Python module composed of two parts:

• some functions defining a public interface,
• an implementation class used by the above functions, but which is not meaningful outside the module.

At first, I decided to "hide" this implementation class by defining it inside the function using it, but this hampers readability and cannot be used if multiple functions reuse the same class.

So, in addition to comments and docstrings, is there a mechanism to mark a class as "private" or "internal"? I am aware of the underscore mechanism, but as I understand it it only applies to variables, function and methods name.

Solution 1:

Use a single underscore prefix:

class _Internal:
    ...

This is the official Python convention for 'internal' symbols; "from module import *" does not import underscore-prefixed objects.

Reference to the single underscore convention.

Solution 2:

In short:

1. You cannot enforce privacy. There are no private classes/methods/functions in Python. At least, not strict privacy as in other languages, such as Java.

2. You can only indicate/suggest privacy. This follows a convention. The Python convention for marking a class/function/method as private is to preface it with an _ (underscore). For example, def _myfunc() or class _MyClass:. You can also create pseudo-privacy by prefacing the method with two underscores (for example, __foo). You cannot access the method directly, but you can still call it through a special prefix using the classname (for example, _classname__foo). So the best you can do is indicate/suggest privacy, not enforce it.

Python is like Perl in this respect. To paraphrase a famous line about privacy from the Perl book, the philosophy is that you should stay out of the living room because you weren't invited, not because it is defended with a shotgun.

For more information:

• Private variables Python Documentation
• Why are Python’s ‘private’ methods not actually private? Stack Overflow question 70528

Solution 3:

Define __all__, a list of names that you want to be exported (see documentation).

__all__ = ['public_class'] # don't add here the 'implementation_class'

Solution 4:

A pattern that I sometimes use is this:

Define a class:

class x(object):
    def doThis(self):
        ...
    def doThat(self):
        ...

Create an instance of the class, overwriting the class name:

x = x()

Define symbols that expose the functionality:

doThis = x.doThis
doThat = x.doThat

Delete the instance itself:

del x

Now you have a module that only exposes your public functions.