[Tutor] __doc__ strings for attributes?

[Evert Rol]

> Thanks for the comments.
>
>> shape0 = BasicShape()
>> shape1 = BasicShape('cylinder', [20.,10.,36.])
>
> I like this way of doing things, I could inherit the 3D data object's
> class and get it to build on itself. I could for example use a
> function definition like the following:
>
> def __init__(*args, **paramDict):
>     self.args = args
>     self.xScanSpacing = paramDict['xScanSpacing']
>     etc.

Careful; your 'self' argument is here included in *args. You'll want  
__init__(self, *args, ...)


> and I get a very flexible base to expand on. I do however get a real
> problem when it comes to documenting the expected keywords and running
> into huge doc strings, when I prefer concise documentation.
>
> I like the following:
>
> class a:
>     def __init__(*args, **paramDict):
>         expectedParam = ['xScanSpacing', 'yScanSpacing'....]
>         paramDocDict = {'xScanSpacing': 'float mm spacing for x axis
> hatches', ...}
>
> To find out what parameters this object works with I could do;
>
>>>> aa = a()
>>>> aa.expectedParam
> ['xScanSpacing', 'yScanSpacing'....]
>>>> aa.paramDocDict['xScanSpacing']
> 'float mm spacing for x axis hatches'
>
> Is there an standard way of doing this?

In line with Kent's remark, I think you'll need doc strings. It's the  
whole point of documentation probably. And if you use the class often  
enough, you'll know the defaults and meaning of parameters anyway; no  
quick lookup needed (after all, here you need to first obtain an  
object from your class, then get the keyword names, before you can  
ask for the actual specifics; by that time, a 'help' on the class  
will have given you the information needed.)

Btw, consider using the help function instead of print the doc string  
(function/method/class.__doc__) additionally gives you the function  
declaration, as long as it's a Python-written function. Ie, you'll  
directly see the required parameters (in won't work for builtin  
functions like map, or the string-strip as below, but will work for  
home-written stuff).
It also gives you a lot more information in general. Compare help 
(dict) versus print dict.__doc__



> This isn't as nice to use as the doc strings and dir function. For
> example if I wanted to find out what I can do with a string I could
> call dir(' ') on the interpreter and have a list of functions and
> attributes contained in the string object. If I wanted a quick
> explanation of one function I could run;
>
>>>> print ' '.strip.__doc__
> S.strip([chars]) -> string or unicode
>
> Return a copy of the string S with leading and trailing
> whitespace removed.
> If chars is given and not None, remove characters in chars instead.
> If chars is unicode, S will be converted to unicode before stripping
>>>>
>
> Cheers,
>
> Wesley Brooks.
>
> On 09/11/2007, Evert Rol <evert.rol at gmail.com> wrote:
>>> How can I add information to an object to explain what it expects as
>>> it's attributes? For instance I may have an object that creates a  
>>> CAD
>>> file based on a set of default values which are set by the __init__
>>> but can be altered before it runs. for example;
>>
>> Why don't you specify a doc-string in your class declaration?
>>
>> class MakeBasicShape:
>>      """basic information
>>
>>      detailed information about attributes
>>      """
>>
>>
>> But, with what you do, why don't you add parameters to MakeIt()?
>>
>>      def MakeIt(self, shape='cuboid', bounds=[0.,10.,0.,10.,0.,10.]):
>>          self.boundsInfo = [shape, bounds]
>>
>>
>> Or perhaps, let your class be the object you're creating (and rename
>> it to 'BasicShape'; verbs in class names seem a bit odd to me)? The
>> __init__ method would then fulfill the function of the MakeIt method,
>> and things would become:
>> shape0 = BasicShape()
>> shape1 = BasicShape('cylinder', [20.,10.,36.])
>> etc.
>>
>> That is, unless you're doing other things in your factory object that
>> don't show up here.
>>
>>
>>>     def MakeIt(self):
>>>         assert self.boundsInfo[0] in self.boundsOptions,
>>>                "Option not recognised: %s", self.boundsInfo[0]
>>
>> I also wouldn't use assert, but try: except:  in MakeIt() for example
>> (assert is really for debugging, but here it looks more like you're
>> trying to prevent user mistakes).
>>
>>
>> Anyway, hope that that gets you further.
>>
>>    Evert
>>
>>
>>>         if self.boundsInfo[0] == 'cuboid'
>>>             bounds = self.boundsInfo[1]
>>>             .... # code to make box
>>>         elif self.boundsInfo[0] == 'cylinder'
>>>             [height, radius, noSides] = self.boundsInfo[1]
>>>             .... # code to make cylinder
>>>         elif self.boundsInfo[0] == 'cad'
>>>             fileName = self.boundsInfo[1]
>>>             .... # code to load CAD file
>>>         return shape
>>>
>>>
>>> if __name__ == '__main__':
>>>     shapeFactory0 = MakeBasicShape()
>>>     shape0 = shapeFactory.MakeIt() # a box
>>>
>>>     shapeFactory1 = MakeBasicShape()
>>>     shapeFactory1.boundsInfo = ['cylinder' ,[20.,10.,36]]
>>>     shape1 = shapeFactory.MakeIt() # a cylinder
>>>
>>>     shapeFactory2 = MakeBasicShape()
>>>     shapeFactory2.boundsInfo = ['cad' ,'/home/Wes/BigHand.stl']
>>>     shape2 = shapeFactory.MakeIt() # a CAD file
>>>
>>> While this example could be coded with different functions for  
>>> making
>>> a box, cylinder, and loading the CAD file I wanted to use attributes
>>> to control the object to simplify interaction with it from the user
>>> interface code. I would like to move away from getters and  
>>> setters as
>>> they're taking up vast chunks of my code at the moment and do very
>>> little!
>>>
>>> Can I also stop new attributes being added to the MakeBasicShape
>>> class?
>>>
>>> Thanks in advance of any help.
>>>
>>> Wesley Brooks
>>>
>>