Python Class Naming – Nested Classes or Composed Names?

class-designdesignnamingobject-orientedpython

I encountered a scenario where I cannot decide on which is the best (or worst) naming strategy. The context is the following: a bracket (as in a tournament) made up of nodes, where is node is made up of two abstract elements which can be a seeded player, a bye, or a reference to another node.

We clearly see a hierarchy of inclusion, conceptually speaking:

Bracket > Node > Element = Seed, Bye, Reference

I cannot decide whether name them with composed names and declare each class at the same level (no nesting):

class Bracket:
    pass

class BracketNode:
    pass

class BracketNodeElement:
    pass

class BracketNodeElementSeed(BracketNodeElement):
    pass

class BracketNodeElementBye(BracketNodeElement):
    pass

class BracketNodeElementReference(BracketNodeElement):
    pass

Or wheter be a bit more DRY with the names but making the name arguably uglier:

class Bracket:
    class Node:
        class Element:
           pass

        class Seed(Element):
           pass

        class Bye(Element):
           pass

        class Reference(Element):
           pass

Accessing a seed or a bye must be expressed this way: Bracket.Node.Seed and Bracket.Node.Bye.

What is the usual way to go?

Best Answer

Option C: simpler is better. Make each class at the global level, and remove the prefix:

class Bracket:
    pass

class Node:
    pass

class Element:
    pass

class Seed(Element):
    pass

class Bye(Element):
    pass

class Reference(Element):
    pass

The fact that these all exist in a module gives you the namespacing you need without having to have large, cumbersome class names. For example, assuming you've put these in a file named tournament.py, then from anywhere else you would use tournament.Bracket, tournament.Node, etc.

Related Solutions

Python Class Design – Impact of Dynamically Generating Classes

You seem to have an appreciation of the trade-offs involved here. As you say, since you know all the information about your classes in advance, it doesn't quite make sense to generate them dynamically.

One alternative to reduce your boring duplicated boilerplate code is to use Python's wonderful support for metaprogramming. If all your refresh methods follow a similar template but the details vary due to the names and types of your classes' attributes, it makes sense to use a metaclass to generate this method when the class is created. In other words, you keep your class statements, and you still declare your class members statically in code, but the information about the refresh boilerplate is kept in one place (in the template that is used by the metaclass). (You could get the same effect using a regular base class and introspection; without more details about your code, I can't give you a clear assessment of what approach would be a good fit for your problem.)

A second option would be to use a code generator. This typically takes the form of a script which takes (for example) some XML or YAML defining your objects as input, and writes out a valid Python file into your build directory. Don't check the generated code into source control; instead just run the generator script every time you build the code. This way you still get file/line information when debugging, and the resulting code is typically not too hard to understand because it's mostly boilerplate. On the other hand, you can't directly edit the file once you've diagnosed a problem because it'll be overwritten next time you run a build - you have to modify the generator. So this approach still has many of the advantages and disadvantages of full-blown runtime class creation.

Another question you should consider asking is "Do we really know everything about these objects in advance?". 20 similar classes is a lot, and it suggests to me that a future requirements change may in fact need you to load these classes at runtime. While you should of course follow YAGNI, you can still design your code in such a way that this change would be easy to make in future. This is another way in which metaprogramming can help you out.

Python – When to Create a Single Class Instance vs Working with the Class

Given a Python class which will be instantiated only once, i.e. there will be only one object of the class. I was wondering in which cases it makes sense to create a single class instance instead of working directly with the class instead.

So it's this:

class Singleton:
    '''don't bother instantiating me'''
    clsvar1 = 'foo'

    @classmethod
    def foobar(cls, *args, **kwargs):
        if condition():
            cls.clsvar1 = 'bar'

versus this?

class Singleton:
    '''instantiate and use me'''
    def __init__(self):
        self.var1 = 'foo'

    def foobar(self, *args, **kwargs):
        if condition():
            self.var1 = 'bar'

Recommendation

I definitely would prefer the one that's intended to be instantiated. When you create a "type of thing" that implies that you create things of that type.

The motivation is to group related code and data and having an interface to it.

That said, why not just use a module since all you want is a namespace? Modules are singletons, group related code and data, and this is a bit simpler and probably would be considered more Pythonic:

var1 ='foo'

def foobar(*args, **kwargs):
    global var1
    if condition():
        var1 = 'bar'

So the usage would be instead of:

from modules.singleton import Singleton
Singleton.foobar()

from modules.singleton import Singleton
the_singleton = Singleton()
the_singleton.foobar()

do this:

from modules import singleton
singleton.foobar()

Best Answer

Related Solutions

Python Class Design – Impact of Dynamically Generating Classes

Python – When to Create a Single Class Instance vs Working with the Class

Related Topic