On 10 August 2018 at 11:13, Erik Bray <erik.m.b...@gmail.com> wrote: > On Thu, Aug 9, 2018 at 4:46 PM Erik Bray <erik.m.b...@gmail.com> wrote: > > > > On Thu, Aug 9, 2018 at 4:26 PM William Stein <wst...@gmail.com> wrote: > > > > > > On Thu, Aug 9, 2018 at 6:20 AM, Simon King <simon.k...@uni-jena.de> > wrote: > > > > Hi Eric, > > > > > > > > On 2018-08-09, Erik Bray <erik.m.b...@gmail.com> wrote: > > > >> But it got me thinking: Maybe it would actually be nice if most Sage > > > >> classes--or at least those inheriting from SageObject, had some > > > >> version of this .help() method. Although we already do a decent job > > > >> advertising the ? and ?? syntax, having .help() method is > inherently > > > >> more discoverable (an the help methods in sandpiles even advertise > the > > > >> ? syntax for further details). > > > > > > I would move anything in a help method to docstrings and deprecate > > > these help methods. > > > Docstrings is where documentation in the source code belongs. It > > > sounds to me like these > > > help methods generate documentation that is NOT included in the > > > reference manual, and > > > that people who know about docstrings mainly might not find. > > > > Did you read my follow-up to Simon? It does not generate > > documentation that is not included in the reference manual. These > > contents of these .help() methods are generated from the docstrings of > > the classes' methods as you can see in the example I posted. It's > > just a different, and more succinct (you should like that!) way of > > displaying the same information that already exists. It also points > > the user to the '?' syntax for more information. > > > > > > I think such method would be fairly useless. > > > > Reason: If a user seeks help about X by trying X.help() rather than > > > > help(X) apparently knows about methods, as a corollary knows about > > > > Python, and as a corollary knows about ? and ??. > > > > > > > > While a .help() METHOD seems useless to me, a help() FUNCTION might > be > > > > useful for newbies. Say, help(X) could print a pointer to the "?" > syntax > > > > (so that the newby will soon be a bit less newby) and then print the > doc > > > > string of X. > > > > > > There is a help function *built into Python* already. That's why Sage > says: > > > > > > 'Type "help()" for help.' > > > > > > on startup. > > > > That is helpful! It should probably also say something about > > tab-completion. However, while help() with no arguments displays some > > custom help text for sage, help(<obj>) just seems to fall back to the > > default Python help(<obj>) functionality, which does *not* have the > > Sage-specific enhancements we make to the <obj>? help. > > > > It would probably be better, at the very least, if "help(<obj>)" an > > "<obj>?" were identical, and not confusingly different. (Also, the > > "<obj>?" syntax is unique to IPython, so even someone familiar with > > Python but not much IPython experience might not know it). > > > > Anyways, I'm not in love with the idea or anything but it seems more > > helpful to users to have more ways to get help. > > One other thing I noticed is that Python's default `help(Integer)` > gives you all the methods defined on Integer as well as their > docstrings, where as `Integer?` just gives the class docstring, but > does not list the methods. > > So if you want to look up all the methods on an object, the only way > seems to be `help(<obj>)`, which is confusingly different (to a user) > from `<obj>?`, or tab completion with `<obj>.<tab>` which can be > tedious, hard to search through, and not always accessible. >
Here's one thing which might confuse beginners using help(). For integers, help(Integer) and help(0) give the same output (which is of course different from help(int)). But in general you may see different things when objects are not constructed via the class name. For example help(NumberField) gives information about the NumberField constructor, while after creating one, say with K=NumberField(x^2+1,'i'), help(K) gives you the methods for that object as well as telling you that it's type is NumberField_quadratic_with_category. > > Am I missing something? If I want to list all the methods an > attributes of an object in Sge, what is the best way to do that > currently? > > -- > You received this message because you are subscribed to the Google Groups > "sage-devel" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to sage-devel+unsubscr...@googlegroups.com. > To post to this group, send email to sage-devel@googlegroups.com. > Visit this group at https://groups.google.com/group/sage-devel. > For more options, visit https://groups.google.com/d/optout. > -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at https://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
