"self" sometimes gets substituted in class docstrings

[cnassau]

Execute the following in a Sage 5.5 notebook cell:

class Test(SageObject):
    """
    TESTS::

        sage: #define a test class
        sage: class SubTest(SageObject):
        ...       def somefunc(self):
        ...          print self.blubb 
    """
    pass

In the next cell execute "Test?". You'll find that "print self.blubb" has been changed to "print Test.blubb".

Component: misc

Issue created by migration from https://trac.sagemath.org/ticket/13969

[jhpalmieri]

comment:1

I think this is due to this line in sageinspect.py. Before just changing it, you should perhaps ask about it on sage-devel.

By the way, this is not notebook-specific: from the command line, execute "ed" to open an editor. Paste your example into it, save and quit. Then do Test?

[cnassau]

comment:2

By the way, this is not notebook-specific: from the command line, execute "ed" to open an editor. Paste your example into it, save and quit. Then do Test?

Somehow I cannot reproduce this from the command line, neither directly nor using a temporary file via "ed". But the line that you pointed out definitely seems to be the culprit.

I managed to find an example of this problem "in the wild": if you ask for CombinatorialFreeModule.__init__? in a notebook cell you get (somewhere in the middle)

sage: class MyAlgebra(CombinatorialFreeModule):
...       def _repr_(self):
...           return "MyAlgebra on %s"%(CombinatorialFreeModule.basis().keys())
...       def product_on_basis(self,i,j):
...           pass

Here "CombinatorialFreeModule.basis().keys()" should really be "self.basis().keys()".

[cnassau]

comment:3

Here are two cases where the substitution of "self" to "objname" is probably desired; note that both contain instances of "self", but only "self." is substituted. So the current substitution mechanism is already a little bit broken:

Z = random_matrix(GF(2),10,10)
Z.rows?

U=RIF(1, 2)
U.diameter?

There are plenty of cases where the substitution is probably not desired. Such cases can be found with

grep -irn "\.\.\..*self\." devel/sage/sage/*/*py*

For example

sage: sage.structure.parent?

shows

sage: class A_class(Parent):
...     def __init__(self, name):
...         Parent.__init__(self, name=name)
...         sage._populate_coercion_lists_()
...         sage.rename(name)

(note the substitution "self." -> "sage.").

I would suggest to

• remove the automatic substitution "self." -> "obj_name."
• introduce a new substitution "OBJNAME" -> "obj_name" and use "self" as default object name if none is provided.

This way we would still support dynamic object name replacement, but the replacement would be restricted to those cases where the docstring author explicitly asked for it.

[nbruin]

comment:4

Keep in mind that the substitution code is not run on the command line, so

sage: Z = random_matrix(GF(2),10,10)
sage: Z.rows?

does not produce docs with the substitution performed. That documentation would suffer from the use of OBJNAME rather than self (since self does have a meaning in that context). I think removing the automatic substitution is a good idea (because it's so hard to decide when it is desirable and when not), but I'm not so sure introducing a more technical alternative is worth it. The whole idea of RST documentation is that the text is also readable in unformatted form. This would be yet another step away from that.