Python module docs instantiating class in argument

Question

I've got a class that I'm trying to document with Sphinx. The module that contains the class below (only first part of class shown)

class StructureContainer:
    """
    Data structure for describing a collection of Particles
    """

    def __init__(self, ptclC=ParticleContainer()):
       …

is included in my sphinx documentation with code like:

.. automodule:: structureContainer
   :members:
   :show-inheritance:

Which works fine. But the default value of ptclC above in supposed to be the default constructor for another class 'ParticleContainer'. But in the documentation it looks as if the constructor is being instantiated in the documentation itself (sorry I can't post image)

class structureContainer.StructureContainer(ptclC=<particles.ParticleContainer instance at 0x1071ed710>,

How can the object instance info be left out of the HTML documentation?

Fwiw, be careful about assigning mutable references as a default parameter value. All your instances wo a ptclC explicitly passed in will be sharing the *same* ptclC instance... May or may not be what you want. — JL Peyret, Aug 07 '15 at 02:20
See http://stackoverflow.com/questions/1132941/least-astonishment-in-python-the-mutable-default-argument?rq=1 — JL Peyret, Aug 07 '15 at 02:33
Thanks for the reply JL. I'll give that a try in my sphinx docs build. I'd like to understand your comment a bit more for my own education. I definitely don't want this container to share the same ptclC instance. I just don't see why that would be the case. Isn't the default argument ParticleContainer() using its constructor to create a different object? (ParticleContainer is another class in my code BTW). — Scott Sides, Aug 07 '15 at 16:04
What happens with a default param value is that it gets "built" at function definition time. Which is why Sphinx is showing a memory allocation address in your doc, btw. You're thinking, "oh it gets built every call wo a ptclC", but that is not the case at all, 1 time only. On an immutable instance, like a string or a number, that's fine and it doesn't matter. Python is, generally, very predictable in what a piece of code will do. This is one of its few edge cases and if you are planning to do any serious Python, read up on that stackoverflow link I posted above. Much better explained. — JL Peyret, Aug 07 '15 at 18:43

score 0 · Answer 1 · answered Aug 07 '15 at 02:26

So, to elaborate and perhaps fix your problem as well...

def __init__(self, ptclC=None):
     if ptclC is None:        
         ptclC =ParticleContainer()

The reason I am answering this is because I think Sphinx is, correctly, showing that you're instantiating at function definition time.

Python module docs instantiating class in argument

1 Answers1