Aliases

[Peleg Michaeli]

I have an ongoing problem with understanding how I should treat aliases in Sage.

I have implemented a new method for Graph, named degeneracy. Another term which is sometimes used to describe degeneracy is linkage. So I have something like:

@doc_index("Degeneracy")
def degeneracy(self):
    r"""
    ...
    """
    return ...

linkage = degeneracy

I have tried something similar while implementing a couple of isoperimetric numbers of graphs (see https://trac.sagemath.org/ticket/21942).

However, after building the docs I see in doc/sage/html/en/reference/graphs/sage/graphs/graph.html, under the heading Degeneracy, two methods: cores() (which was there, I have just modified its doc_index) and linkage(). No degeneracy(). I would be the best to have there degeneracy() only, but perhaps even having both is acceptable; but not only linkage() (which is just an alias, in my opinion it is a much less common term, at least in the community of graph theorists).

Have I done anything wrong here?


Thanks,
Peleg.

[Travis Scrimshaw]

Hey Peleg,
   Here is what I think is going on, the @doc_index is modifying the method degeneracy, i.e., it creates a new method with the same name of "degeneracy" and has a link back to the actual method. Then the new degeneracy also gets assigned to the name linkage. Now when the documentation is built, both of the modified functions link to the same actual method, which gets put into the doc twice, and it is the last one (in this case, linkage) that remains.

So I would say this is a bug in @doc_index decorator, and you will need to go into that code and give it the ability to handle proper aliases.

Best,
Travis

[Jori Mäntysalo]

On Wed, 7 Dec 2016, Peleg Michaeli wrote:

> I have an ongoing problem with understanding how I should treat aliases in
> Sage.

Travis gave a technical answer.

But what about just implementing degeneracy() with docstring containing
"This is also called linkage."? Compare to is_series_parallel() on
src/sage/combinat/posets/posets.py.

(IMO tab completion could even show linkage() when g.l<tab> is pressed and
show something like "linkage (alias to degeneracy)", but that's not a
decision that Sage should do, it should be a property of IPython.)

--
Jori Mäntysalo

[Robert Dodier]

On 2016-12-07, Peleg Michaeli <free...@gmail.com> wrote:

> I have implemented a new method for Graph, named *degeneracy*. Another term
> which is sometimes used to describe degeneracy is *linkage*. So I have

> something like:
>
> @doc_index("Degeneracy")
> def degeneracy(self):
> r"""
> ...
> """
> return ...
>
> linkage = degeneracy

I dunno. Aliases are a source of ambiguity and confusion -- my advice
is to pick one or the other and stick with it. Are you sure the
convenience outweighs the potential problems?

best,

Robert Dodier

[Sébastien Labbé]

I dunno. Aliases are a source of ambiguity and confusion -- my advice
is to pick one or the other and stick with it.

+1

[Peleg Michaeli]

OK then, I'll simply add aliases in the docstrings (however, note that there are places in sage with such aliases, such as `am = adjacency_matrix`).

[Jori Mäntysalo]

On Wed, 14 Dec 2016, Peleg Michaeli wrote:

> OK then, I'll simply add aliases in the docstrings (however, note that
> there are places in sage with such aliases, such as `am =
> adjacency_matrix`).

Yes, there are. And I think they should be mostly deprecated and later
deleted. /Except something like ZZ which is very common and have quite
long "real" name.)

Btw, is there an easy way for a user to add own aliases? So that it would
go to the right place in hierarchy.

--
Jori Mäntysalo

[TB]

I had a short discussion about aliases in Sage Days 79. It might be
appropriate for general Python programming to have an alias() function
for adding aliases of functions and methods.

The usage should be something like:
new_alias = alias("new_alias", orig_function)

It should copy the docstring of orig_function and prepend to it
"new_alias is an alias of orig_function\n". For better documentation it
should also add to orig_function the existence of such aliases. One way
to implement it is to add an attribute orig_function._aliases to be the
list of aliases. Then, the docstring of orig_function will have an
ALIASES section (dynamically created) in its documentation if _aliases
exist and is not empty.

It gets trickier to implement for methods in Cython classes and Python
classes that only use __slots__, because we need to dynamically add
attributes.

For class methods, having such an alias() function helps with
inheritance, not just with citations. Suppose we have

class A(object):
def foo(self):
print "A.foo"
also_foo = foo

class B(A):
def foo(self):
print "B.foo"

Then we get different behavior of foo() and also_foo() in B:
sage: b = B()
sage: b.foo()
B.foo
sage: b.also_foo() # Surprise!
A.foo

BTW, tab completion is not enough to discover aliases, because not all
aliases are prefixes. See for example the short docstring of
gaussian_binomial which is an alias for q_binomial.

Regards,
TB