self-documenting Python code

Question

I have the following piece of Python:

class CollectorGUI(Gtk.Window):
    def __init__(self, prefill, flags, data_to_return):
        """prefill should be an instance of the Prefill class"""
        self.prefill = prefill
        self.flags = flags
        self.data_to_return = data_to_return
    ......

My question is: (1) how to get rid of the documentation string? I want my code to be self-documenting; (2) how to get rid of these three lines:

self.prefill = prefill
self.flags = flags
self.data_to_return = data_to_return

Is there an abbreviation?

_"how to get rid of the documentation string?"_ Did it give an error or something when you tried simply deleting it? — Kevin, May 15 '14 at 14:00
[What is the best way to do automatic attribute assignment in Python, and is it a good idea?](http://stackoverflow.com/q/3652851) — Martijn Pieters, May 15 '14 at 14:00
@Kevin: the OP means that they want it to be clear from the method signature that `prefill` should be certain type, rather than to have to document it. The answer is: use annotations. — Martijn Pieters, May 15 '14 at 14:01
Oh, I see. As in, "how to get rid of the docstring [, while still making that information evident]?" — Kevin, May 15 '14 at 14:02
Thank you, Martijn Pieters, this is exactly what I was trying to figure out. — amkhlv, May 15 '14 at 16:00

score 4 · Accepted Answer · edited May 23 '17 at 11:57

The Prefill requirement can be documented in the method signature using function annotations:

class CollectorGUI(Gtk.Window):
    def __init__(self, prefill: Prefill, flags, data_to_return):

Annotations are discoverable at runtime, just like the docstring is. Annotations are not enforced (they are meant as a more generic stepping stone for different use cases) but are immediately obvious in the signature.

You can then optionally enforce it explicitly by asserting the type:

assert isinstance(prefill, Prefill), 'prefill must be an instance of Prefill'

As for auto-setting your attributes from the function arguments, that's answered elsewhere: What is the best way to do automatic attribute assignment in Python, and is it a good idea?

score 0 · Answer 2 · answered May 15 '14 at 14:19

While you could use inspect to automatically create attributes from the arguments in the method's signature, it would obfuscate the perfectly readable code you have now. One look at the constructor tells me that the class at least has the attributes prefill, flags, and data_to_return.

Making explicit code implicit is often not a good idea.

But if you insist:

import inspect


class C(object):

  def __init__(self, a, b, c):
      spec = inspect.getargspec(getattr(C, "__init__"))
      for arg in spec.args[1:]:
        setattr(self, arg, locals()[arg])



c = C(1, 2, 3)

print c.a
print c.b
print c.c

Yes, that works. Thank you. But it seems that there is an even simpler way, as suggested by Martijn Peters. — amkhlv, May 15 '14 at 16:03

self-documenting Python code

2 Answers2