python - should I use static methods or top-level functions

In Java there's the (IMHO wrong) idea to use classes everywhere, even just group together static functions that don't share any state (and thus such classes will never be instantiated).

Python here begs to differ; if you have functions that don't have some shared state¹ (and thus in Java would typically be static functions) and aren't tightly related to a "real" class (=one that is actually instantiated) you just use free functions inside a module.

The reasoning behind this is that a class is needed only when you actually want to instantiate it, thus having a class just as a container for several functions that don't need to share an instance-specific state is useless.

Actually, you can somewhat think of a module as a static class - i.e. a container of functions (=static methods), module variables (=static fields) and types.

The nice thing in Python is that having top-level function doesn't give global namespace pollution problems, since in Python top-level functions/objects/... are still module-scoped. Thus, you can still group functions by module, without the unnecessary class-tax.

1. actually, they can have some shared state, in form of module-level variables (so, singletons); again, the analogy modules-static classes seems to hold.

From the Zen of Python (import this) :

Namespaces are one honking great idea -- let's do more of those!

One of the main reasons to create static methods in a language like Java is to ensure that those methods don't wind up polluting the global namespace. (Although Java enforces its own namespace conventions by disallowing "package-level" functions entirely !) In Python, all "top-level" functions are automatically placed within the namespace of the module containing those functions, so there's no danger of polluting the global namespace this way.

In other words, like many other languages, Python can create namespaces in a few different ways. In this case, there's little need to create a class containing only static methods, when a module serves the same namespacing purpose without the clutter (or cognitive load) associated with defining a class.

It a question of namespace pollution. If you have a module with multiple classes and some functions that only make sense for a certain class and its descendents, then make that a static method. The static method can be called either by using the class name or by using an object of the class.

>>> class A(object):...     @staticmethod...     def static_1():...             print 'i am static'...     def a(self):...             self.static_1()...>>> A.static_1()i am static>>> a=A()>>> a.a()i am static>>> a.static_1()i am static>>> class B(A):...     pass...>>> b=B()>>> b.static_1()i am static>>>